##
# @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.
+# As this command is just for limited, ad-hoc debugging, such as log
+# file access, the number of bytes to read is limited to 48 MB.
#
# @handle: filehandle returned by guest-file-open
#
-# @count: maximum number of bytes to read (default is 4KB)
+# @count: maximum number of bytes to read (default is 4KB, maximum is 48MB)
#
# Returns: @GuestFileRead on success.
#
# 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.
+# some other guest processes having issued an fs freeze/thaw.
#
# Since: 0.15.0
##
# unfreeze.
#
# Note: On Windows, the command is implemented with the help of a
-# Volume Shadow-copy Service DLL helper. The frozen state is limited
-# for up to 10 seconds by VSS.
+# Volume Shadow-copy Service DLL helper. The frozen state is limited
+# for up to 10 seconds by VSS.
#
# Returns: Number of file systems currently frozen. On error, all filesystems
-# will be thawed.
+# will be thawed. If no filesystems are frozen as a result of this call,
+# then @guest-fsfreeze-status will remain "thawed" and calling
+# @guest-fsfreeze-thaw is not necessary.
#
# Since: 0.15.0
##
# Invalid mount points are ignored.
#
# Returns: Number of file systems currently frozen. On error, all filesystems
-# will be thawed.
+# will be thawed.
#
# Since: 2.2
##
#
# Discard (or "trim") blocks which are not in use by the filesystem.
#
-# @minimum:
-# Minimum contiguous free range to discard, in bytes. Free ranges
-# smaller than this may be ignored (this is a hint and the guest
-# may not respect it). By increasing this value, the fstrim
-# operation will complete more quickly for filesystems with badly
-# fragmented free space, although not all blocks will be discarded.
-# The default value is zero, meaning "discard every free block".
+# @minimum: Minimum contiguous free range to discard, in bytes. Free ranges
+# smaller than this may be ignored (this is a hint and the guest
+# may not respect it). By increasing this value, the fstrim
+# operation will complete more quickly for filesystems with badly
+# fragmented free space, although not all blocks will be discarded.
+# The default value is zero, meaning "discard every free block".
#
# Returns: A @GuestFilesystemTrimResponse which contains the
# status of all trimmed paths. (since 2.4)
#
# 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.
+# This command attempts to suspend the guest using three strategies, in this
+# order:
#
-# For the best results it's strongly recommended to have the pm-utils
-# package installed in the guest.
+# - systemd hibernate
+# - pm-utils (via pm-hibernate)
+# - manual write into sysfs
#
# 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
# (or set its status to "shutdown") due to other reasons.
#
# The following errors may be returned:
-# If suspend to disk is not supported, Unsupported
+#
+# - 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
#
# 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.
+# This command attempts to suspend the guest using three strategies, in this
+# order:
#
-# For the best results it's strongly recommended to have the pm-utils
-# package installed in the guest.
+# - systemd suspend
+# - pm-utils (via pm-suspend)
+# - manual write into sysfs
#
-# 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.
+# IMPORTANT: guest-suspend-ram requires working wakeup support in
+# QEMU. You should check QMP command query-current-machine returns
+# wakeup-suspend-support: true before issuing this command. Failure in
+# doing so can result in a suspended guest that QEMU will not be able to
+# awaken, forcing the user to power cycle the guest to bring it back.
#
# 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"
+#
+# 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
+#
+# - 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
#
# Save guest state to disk and suspend to ram.
#
-# This command requires the pm-utils package to be installed in the guest.
+# This command attempts to suspend the guest by executing, in this order:
#
-# 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.
+# - systemd hybrid-sleep
+# - pm-utils (via pm-suspend-hybrid)
+#
+# IMPORTANT: guest-suspend-hybrid requires working wakeup support in
+# QEMU. You should check QMP command query-current-machine returns
+# wakeup-suspend-support: true before issuing this command. Failure in
+# doing so can result in a suspended guest that QEMU will not be able to
+# awaken, forcing the user to power cycle the guest to bring it back.
#
# 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"
+#
+# 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
+#
+# - 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
# @ip-addresses: List of addresses assigned to @name
#
# @statistics: various statistic counters related to @name
-# (since 2.11)
+# (since 2.11)
#
# Since: 1.1
##
# This is a read-only operation.
#
# Returns: The list of all VCPUs the guest knows about. Each VCPU is put on the
-# list exactly once, but their order is unspecified.
+# list exactly once, but their order is unspecified.
#
# Since: 1.5
##
# Returns: The length of the initial sublist that has been successfully
# processed. The guest agent maximizes this value. Possible cases:
#
-# - 0: if the @vcpus list was empty on input. Guest state
-# has not been changed. Otherwise,
-# - Error: processing the first node of @vcpus failed for the
-# reason returned. Guest state has not been changed.
-# Otherwise,
-# - < length(@vcpus): more than zero initial nodes have been processed,
-# but not the entire @vcpus list. Guest state has
-# changed accordingly. To retrieve the error
-# (assuming it persists), repeat the call with the
-# successfully processed initial sublist removed.
-# Otherwise,
-# - length(@vcpus): call successful.
+# - 0:
+# if the @vcpus list was empty on input. Guest state
+# has not been changed. Otherwise,
+# - Error:
+# processing the first node of @vcpus failed for the
+# reason returned. Guest state has not been changed.
+# Otherwise,
+# - < length(@vcpus):
+# more than zero initial nodes have been processed,
+# but not the entire @vcpus list. Guest state has
+# changed accordingly. To retrieve the error
+# (assuming it persists), repeat the call with the
+# successfully processed initial sublist removed.
+# Otherwise,
+# - length(@vcpus):
+# call successful.
#
# Since: 1.5
##
# @sas: Win serial-attaches SCSI bus type
# @mmc: Win multimedia card (MMC) bus type
# @virtual: Win virtual bus type
-# @file-backed virtual: Win file-backed bus type
+# @file-backed-virtual: Win file-backed bus type
#
# Since: 2.2; 'Unknown' and all entries below since 2.4
##
# @bus: bus id
# @target: target id
# @unit: unit id
+# @serial: serial number (since: 3.1)
+# @dev: device node (POSIX) or device UNC (Windows) (since: 3.1)
#
# Since: 2.2
##
{ 'struct': 'GuestDiskAddress',
'data': {'pci-controller': 'GuestPCIAddress',
'bus-type': 'GuestDiskBusType',
- 'bus': 'int', 'target': 'int', 'unit': 'int'} }
+ 'bus': 'int', 'target': 'int', 'unit': 'int',
+ '*serial': 'str', '*dev': 'str'} }
##
# @GuestFilesystemInfo:
# @name: disk name
# @mountpoint: mount point path
# @type: file system type string
+# @used-bytes: file system used bytes (since 3.0)
+# @total-bytes: non-root file system total bytes (since 3.0)
# @disk: an array of disk hardware information that the volume lies on,
# which may be empty if the disk type is not supported
#
##
{ 'struct': 'GuestFilesystemInfo',
'data': {'name': 'str', 'mountpoint': 'str', 'type': 'str',
+ '*used-bytes': 'uint64', '*total-bytes': 'uint64',
'disk': ['GuestDiskAddress']} }
##
# This is a read-only operation.
#
# Returns: The list of all memory blocks the guest knows about.
-# Each memory block is put on the list exactly once, but their order
-# is unspecified.
+# Each memory block is put on the list exactly once, but their order
+# is unspecified.
#
# Since: 2.3
##
# @response: the result of memory block operation.
#
# @error-code: the error number.
-# When memory block operation fails, we assign the value of
-# 'errno' to this member, it indicates what goes wrong.
-# When the operation succeeds, it will be omitted.
+# When memory block operation fails, we assign the value of
+# 'errno' to this member, it indicates what goes wrong.
+# When the operation succeeds, it will be omitted.
#
# Since: 2.3
##
# @exited: true if process has already terminated.
# @exitcode: process exit code if it was normally terminated.
# @signal: signal number (linux) or unhandled exception code
-# (windows) if the process was abnormally terminated.
+# (windows) if the process was abnormally terminated.
# @out-data: base64-encoded stdout of the process
# @err-data: base64-encoded stderr of the process
-# Note: @out-data and @err-data are present only
-# if 'capture-output' was specified for 'guest-exec'
+# Note: @out-data and @err-data are present only
+# if 'capture-output' was specified for 'guest-exec'
# @out-truncated: true if stdout was not fully captured
-# due to size limitation.
+# due to size limitation.
# @err-truncated: true if stderr was not fully captured
-# due to size limitation.
+# due to size limitation.
#
# Since: 2.5
##
##
# @GuestUser:
-# @user: Username
-# @domain: Logon domain (windows only)
+# @user: Username
+# @domain: Logon domain (windows only)
# @login-time: Time of login of this user on the computer. If multiple
# instances of the user are logged in, the earliest login time is
# reported. The value is in fractional seconds since epoch time.
##
# @GuestTimezone:
#
-# @zone: Timezone name. These values may differ depending on guest/OS and
-# should only be used for informational purposes.
-# @offset: Offset to UTC in seconds, negative numbers for time zones west of
-# GMT, positive numbers for east
+# @zone: Timezone name. These values may differ depending on guest/OS and
+# should only be used for informational purposes.
+# @offset: Offset to UTC in seconds, negative numbers for time zones west of
+# GMT, positive numbers for east
#
# Since: 2.10
##
# @GuestOSInfo:
#
# @kernel-release:
-# * POSIX: release field returned by uname(2)
-# * Windows: version number of the OS
+# * POSIX: release field returned by uname(2)
+# * Windows: build number of the OS
# @kernel-version:
-# * POSIX: version field returned by uname(2)
-# * Windows: build number of the OS
+# * POSIX: version field returned by uname(2)
+# * Windows: version number of the OS
# @machine:
-# * POSIX: machine field returned by uname(2)
-# * Windows: one of x86, x86_64, arm, ia64
+# * POSIX: machine field returned by uname(2)
+# * Windows: one of x86, x86_64, arm, ia64
# @id:
-# * POSIX: as defined by os-release(5)
-# * Windows: contains string "mswindows"
+# * POSIX: as defined by os-release(5)
+# * Windows: contains string "mswindows"
# @name:
-# * POSIX: as defined by os-release(5)
-# * Windows: contains string "Microsoft Windows"
+# * POSIX: as defined by os-release(5)
+# * Windows: contains string "Microsoft Windows"
# @pretty-name:
-# * POSIX: as defined by os-release(5)
-# * Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
+# * POSIX: as defined by os-release(5)
+# * Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
# @version:
-# * POSIX: as defined by os-release(5)
-# * Windows: long version string, e.g. "Microsoft Windows Server 2008"
+# * POSIX: as defined by os-release(5)
+# * Windows: long version string, e.g. "Microsoft Windows Server 2008"
# @version-id:
-# * POSIX: as defined by os-release(5)
-# * Windows: short version identifier, e.g. "7" or "20012r2"
+# * POSIX: as defined by os-release(5)
+# * Windows: short version identifier, e.g. "7" or "20012r2"
# @variant:
-# * POSIX: as defined by os-release(5)
-# * Windows: contains string "server" or "client"
+# * POSIX: as defined by os-release(5)
+# * Windows: contains string "server" or "client"
# @variant-id:
-# * POSIX: as defined by os-release(5)
-# * Windows: contains string "server" or "client"
+# * POSIX: as defined by os-release(5)
+# * Windows: contains string "server" or "client"
#
# Notes:
#
projects / mirror_qemu.git / blobdiff