| @c AUTOMATICALLY GENERATED, DO NOT MODIFY |
| |
| @section Introduction |
| |
| This document describes all commands currently supported by QMP. |
| |
| Most of the time their usage is exactly the same as in the user Monitor, this |
| means that any other document which also describe commands (the manpage, |
| QEMU's manual, etc) can and should be consulted. |
| |
| QMP has two types of commands: regular and query commands. Regular commands |
| usually change the Virtual Machine's state someway, while query commands just |
| return information. The sections below are divided accordingly. |
| |
| It's important to observe that all communication examples are formatted in |
| a reader-friendly way, so that they're easier to understand. However, in real |
| protocol usage, they're emitted as a single line. |
| |
| Also, the following notation is used to denote data flow: |
| |
| Example: |
| |
| @example |
| -> data issued by the Client |
| @end example |
| |
| @example |
| <- Server data response |
| @end example |
| |
| |
| Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for |
| detailed information on the Server command and response formats. |
| |
| @section Stability Considerations |
| |
| The current QMP command set (described in this file) may be useful for a |
| number of use cases, however it's limited and several commands have bad |
| defined semantics, specially with regard to command completion. |
| |
| These problems are going to be solved incrementally in the next QEMU releases |
| and we're going to establish a deprecation policy for badly defined commands. |
| |
| If you're planning to adopt QMP, please observe the following: |
| |
| @enumerate |
| @item |
| The deprecation policy will take effect and be documented soon, please |
| check the documentation of each used command as soon as a new release of |
| QEMU is available |
| |
| @item |
| DO NOT rely on anything which is not explicit documented |
| |
| @item |
| Errors, in special, are not documented. Applications should NOT check |
| for specific errors classes or data (it's strongly recommended to only |
| check for the "error" key) |
| @end enumerate |
| |
| |
| @section Common data types |
| |
| |
| @deftp {Enum} QapiErrorClass |
| |
| QEMU error classes |
| |
| @b{Values:} |
| @table @asis |
| @item @code{GenericError} |
| this is used for errors that don't require a specific error |
| class. This should be the default case for most errors |
| @item @code{CommandNotFound} |
| the requested command has not been found |
| @item @code{DeviceNotActive} |
| a device has failed to be become active |
| @item @code{DeviceNotFound} |
| the requested device has not been found |
| @item @code{KVMMissingCap} |
| the requested operation can't be fulfilled because a |
| required KVM capability is missing |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} IoOperationType |
| |
| An enumeration of the I/O operation types |
| |
| @b{Values:} |
| @table @asis |
| @item @code{read} |
| read operation |
| @item @code{write} |
| write operation |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} OnOffAuto |
| |
| An enumeration of three options: on, off, and auto |
| |
| @b{Values:} |
| @table @asis |
| @item @code{auto} |
| QEMU selects the value between on and off |
| @item @code{on} |
| Enabled |
| @item @code{off} |
| Disabled |
| @end table |
| |
| @b{Since:} |
| 2.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} OnOffSplit |
| |
| An enumeration of three values: on, off, and split |
| |
| @b{Values:} |
| @table @asis |
| @item @code{on} |
| Enabled |
| @item @code{off} |
| Disabled |
| @item @code{split} |
| Mixed |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} String |
| |
| A fat type wrapping 'str', to be embedded in lists. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{str: string} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Alternate} StrOrNull |
| |
| This is a string value or the explicit lack of a string (null |
| pointer in C). Intended for cases when 'optional absent' already |
| has a different meaning. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{s: string} |
| the string value |
| @item @code{n: null} |
| no string value |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} OffAutoPCIBAR |
| |
| An enumeration of options for specifying a PCI BAR |
| |
| @b{Values:} |
| @table @asis |
| @item @code{off} |
| The specified feature is disabled |
| @item @code{auto} |
| The PCI BAR for the feature is automatically selected |
| @item @code{bar0} |
| PCI BAR0 is used for the feature |
| @item @code{bar1} |
| PCI BAR1 is used for the feature |
| @item @code{bar2} |
| PCI BAR2 is used for the feature |
| @item @code{bar3} |
| PCI BAR3 is used for the feature |
| @item @code{bar4} |
| PCI BAR4 is used for the feature |
| @item @code{bar5} |
| PCI BAR5 is used for the feature |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| @section Socket data types |
| |
| |
| @deftp {Enum} NetworkAddressFamily |
| |
| The network address family |
| |
| @b{Values:} |
| @table @asis |
| @item @code{ipv4} |
| IPV4 family |
| @item @code{ipv6} |
| IPV6 family |
| @item @code{unix} |
| unix socket |
| @item @code{vsock} |
| vsock family (since 2.8) |
| @item @code{unknown} |
| otherwise |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} InetSocketAddressBase |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{host: string} |
| host part of the address |
| @item @code{port: string} |
| port part of the address |
| @end table |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} InetSocketAddress |
| |
| Captures a socket address or address range in the Internet namespace. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{numeric: boolean} (optional) |
| true if the host/port are guaranteed to be numeric, |
| false if name resolution should be attempted. Defaults to false. |
| (Since 2.9) |
| @item @code{to: int} (optional) |
| If present, this is range of possible addresses, with port |
| between @code{port} and @code{to}. |
| @item @code{ipv4: boolean} (optional) |
| whether to accept IPv4 addresses, default try both IPv4 and IPv6 |
| @item @code{ipv6: boolean} (optional) |
| whether to accept IPv6 addresses, default try both IPv4 and IPv6 |
| @item The members of @code{InetSocketAddressBase} |
| @end table |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} UnixSocketAddress |
| |
| Captures a socket address in the local ("Unix socket") namespace. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{path: string} |
| filesystem path to use |
| @end table |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} VsockSocketAddress |
| |
| Captures a socket address in the vsock namespace. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{cid: string} |
| unique host identifier |
| @item @code{port: string} |
| port |
| @end table |
| |
| @b{Note:} |
| string types are used to allow for possible future hostname or |
| service resolution support. |
| |
| @b{Since:} |
| 2.8 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SocketAddressLegacy |
| |
| Captures the address of a socket, which could also be a named file descriptor |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type} |
| One of @t{"inet"}, @t{"unix"}, @t{"vsock"}, @t{"fd"} |
| @item @code{data: InetSocketAddress} when @code{type} is @t{"inet"} |
| @item @code{data: UnixSocketAddress} when @code{type} is @t{"unix"} |
| @item @code{data: VsockSocketAddress} when @code{type} is @t{"vsock"} |
| @item @code{data: String} when @code{type} is @t{"fd"} |
| @end table |
| |
| @b{Note:} |
| This type is deprecated in favor of SocketAddress. The |
| difference between SocketAddressLegacy and SocketAddress is that the |
| latter is a flat union rather than a simple union. Flat is nicer |
| because it avoids nesting on the wire, i.e. that form has fewer @{@}. |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} SocketAddressType |
| |
| Available SocketAddress types |
| |
| @b{Values:} |
| @table @asis |
| @item @code{inet} |
| Internet address |
| @item @code{unix} |
| Unix domain socket |
| @item @code{vsock} |
| VMCI address |
| @item @code{fd} |
| decimal is for file descriptor number, otherwise a file descriptor name. |
| Named file descriptors are permitted in monitor commands, in combination |
| with the 'getfd' command. Decimal file descriptors are permitted at |
| startup or other contexts where no monitor context is active. |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SocketAddress |
| |
| Captures the address of a socket, which could also be a named file |
| descriptor |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: SocketAddressType} |
| Transport type |
| @item The members of @code{InetSocketAddress} when @code{type} is @t{"inet"} |
| @item The members of @code{UnixSocketAddress} when @code{type} is @t{"unix"} |
| @item The members of @code{VsockSocketAddress} when @code{type} is @t{"vsock"} |
| @item The members of @code{String} when @code{type} is @t{"fd"} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| @section VM run state |
| |
| |
| @deftp {Enum} RunState |
| |
| An enumeration of VM run states. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{debug} |
| QEMU is running on a debugger |
| @item @code{finish-migrate} |
| guest is paused to finish the migration process |
| @item @code{inmigrate} |
| guest is paused waiting for an incoming migration. Note |
| that this state does not tell whether the machine will start at the |
| end of the migration. This depends on the command-line -S option and |
| any invocation of 'stop' or 'cont' that has happened since QEMU was |
| started. |
| @item @code{internal-error} |
| An internal error that prevents further guest execution |
| has occurred |
| @item @code{io-error} |
| the last IOP has failed and the device is configured to pause |
| on I/O errors |
| @item @code{paused} |
| guest has been paused via the 'stop' command |
| @item @code{postmigrate} |
| guest is paused following a successful 'migrate' |
| @item @code{prelaunch} |
| QEMU was started with -S and guest has not started |
| @item @code{restore-vm} |
| guest is paused to restore VM state |
| @item @code{running} |
| guest is actively running |
| @item @code{save-vm} |
| guest is paused to save the VM state |
| @item @code{shutdown} |
| guest is shut down (and -no-shutdown is in use) |
| @item @code{suspended} |
| guest is suspended (ACPI S3) |
| @item @code{watchdog} |
| the watchdog action is configured to pause and has been triggered |
| @item @code{guest-panicked} |
| guest has been panicked as a result of guest OS panic |
| @item @code{colo} |
| guest is paused to save/restore VM state under colo checkpoint, |
| VM can not get into this state unless colo capability is enabled |
| for migration. (since 2.8) |
| @end table |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} StatusInfo |
| |
| Information about VCPU run state |
| |
| @b{Members:} |
| @table @asis |
| @item @code{running: boolean} |
| true if all VCPUs are runnable, false if not runnable |
| @item @code{singlestep: boolean} |
| true if VCPUs are in single-step mode |
| @item @code{status: RunState} |
| the virtual machine @code{RunState} |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| @code{singlestep} is enabled through the GDB stub |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-status |
| |
| Query the run status of all VCPUs |
| |
| @b{Returns:} |
| @code{StatusInfo} reflecting all VCPUs |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-status" @} |
| <- @{ "return": @{ "running": true, |
| "singlestep": false, |
| "status": "running" @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} SHUTDOWN |
| |
| Emitted when the virtual machine has shut down, indicating that qemu is |
| about to exit. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{guest: boolean} |
| If true, the shutdown was triggered by a guest request (such as |
| a guest-initiated ACPI shutdown request or other hardware-specific action) |
| rather than a host request (such as sending qemu a SIGINT). (since 2.10) |
| @end table |
| |
| @b{Note:} |
| If the command-line option "-no-shutdown" has been specified, qemu will |
| not exit, and a STOP event will eventually follow the SHUTDOWN event |
| |
| @b{Since:} |
| 0.12.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "SHUTDOWN", "data": @{ "guest": true @}, |
| "timestamp": @{ "seconds": 1267040730, "microseconds": 682951 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} POWERDOWN |
| |
| Emitted when the virtual machine is powered down through the power control |
| system, such as via ACPI. |
| |
| @b{Since:} |
| 0.12.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "POWERDOWN", |
| "timestamp": @{ "seconds": 1267040730, "microseconds": 682951 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} RESET |
| |
| Emitted when the virtual machine is reset |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{guest: boolean} |
| If true, the reset was triggered by a guest request (such as |
| a guest-initiated ACPI reboot request or other hardware-specific action) |
| rather than a host request (such as the QMP command system_reset). |
| (since 2.10) |
| @end table |
| |
| @b{Since:} |
| 0.12.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "RESET", "data": @{ "guest": false @}, |
| "timestamp": @{ "seconds": 1267041653, "microseconds": 9518 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} STOP |
| |
| Emitted when the virtual machine is stopped |
| |
| @b{Since:} |
| 0.12.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "STOP", |
| "timestamp": @{ "seconds": 1267041730, "microseconds": 281295 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} RESUME |
| |
| Emitted when the virtual machine resumes execution |
| |
| @b{Since:} |
| 0.12.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "RESUME", |
| "timestamp": @{ "seconds": 1271770767, "microseconds": 582542 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} SUSPEND |
| |
| Emitted when guest enters a hardware suspension state, for example, S3 state, |
| which is sometimes called standby state |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "SUSPEND", |
| "timestamp": @{ "seconds": 1344456160, "microseconds": 309119 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} SUSPEND_DISK |
| |
| Emitted when guest enters a hardware suspension state with data saved on |
| disk, for example, S4 state, which is sometimes called hibernate state |
| |
| @b{Note:} |
| QEMU shuts down (similar to event @code{SHUTDOWN}) when entering this state |
| |
| @b{Since:} |
| 1.2 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "SUSPEND_DISK", |
| "timestamp": @{ "seconds": 1344456160, "microseconds": 309119 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} WAKEUP |
| |
| Emitted when the guest has woken up from suspend state and is running |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "WAKEUP", |
| "timestamp": @{ "seconds": 1344522075, "microseconds": 745528 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} WATCHDOG |
| |
| Emitted when the watchdog device's timer is expired |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{action: WatchdogAction} |
| action that has been taken |
| @end table |
| |
| @b{Note:} |
| If action is "reset", "shutdown", or "pause" the WATCHDOG event is |
| followed respectively by the RESET, SHUTDOWN, or STOP events |
| |
| @b{Note:} |
| This event is rate-limited. |
| |
| @b{Since:} |
| 0.13.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "WATCHDOG", |
| "data": @{ "action": "reset" @}, |
| "timestamp": @{ "seconds": 1267061043, "microseconds": 959568 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} WatchdogAction |
| |
| An enumeration of the actions taken when the watchdog device's timer is |
| expired |
| |
| @b{Values:} |
| @table @asis |
| @item @code{reset} |
| system resets |
| @item @code{shutdown} |
| system shutdown, note that it is similar to @code{powerdown}, which |
| tries to set to system status and notify guest |
| @item @code{poweroff} |
| system poweroff, the emulator program exits |
| @item @code{pause} |
| system pauses, similar to @code{stop} |
| @item @code{debug} |
| system enters debug state |
| @item @code{none} |
| nothing is done |
| @item @code{inject-nmi} |
| a non-maskable interrupt is injected into the first VCPU (all |
| VCPUS on x86) (since 2.4) |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} watchdog-set-action |
| |
| Set watchdog action |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{action: WatchdogAction} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.11 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} GUEST_PANICKED |
| |
| Emitted when guest OS panic is detected |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{action: GuestPanicAction} |
| action that has been taken, currently always "pause" |
| @item @code{info: GuestPanicInformation} (optional) |
| information about a panic (since 2.9) |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "GUEST_PANICKED", |
| "data": @{ "action": "pause" @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} GuestPanicAction |
| |
| An enumeration of the actions taken when guest OS panic is detected |
| |
| @b{Values:} |
| @table @asis |
| @item @code{pause} |
| system pauses |
| @item @code{poweroff} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.1 (poweroff since 2.8) |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} GuestPanicInformationType |
| |
| An enumeration of the guest panic information types |
| |
| @b{Values:} |
| @table @asis |
| @item @code{hyper-v} |
| hyper-v guest panic information type |
| @item @code{s390} |
| s390 guest panic information type (Since: 2.12) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} GuestPanicInformation |
| |
| Information about a guest panic |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: GuestPanicInformationType} |
| Crash type that defines the hypervisor specific information |
| @item The members of @code{GuestPanicInformationHyperV} when @code{type} is @t{"hyper-v"} |
| @item The members of @code{GuestPanicInformationS390} when @code{type} is @t{"s390"} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} GuestPanicInformationHyperV |
| |
| Hyper-V specific guest panic information (HV crash MSRs) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{arg1: int} |
| Not documented |
| @item @code{arg2: int} |
| Not documented |
| @item @code{arg3: int} |
| Not documented |
| @item @code{arg4: int} |
| Not documented |
| @item @code{arg5: int} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} S390CrashReason |
| |
| Reason why the CPU is in a crashed state. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{unknown} |
| no crash reason was set |
| @item @code{disabled-wait} |
| the CPU has entered a disabled wait state |
| @item @code{extint-loop} |
| clock comparator or cpu timer interrupt with new PSW enabled |
| for external interrupts |
| @item @code{pgmint-loop} |
| program interrupt with BAD new PSW |
| @item @code{opint-loop} |
| operation exception interrupt with invalid code at the program |
| interrupt new PSW |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} GuestPanicInformationS390 |
| |
| S390 specific guest panic information (PSW) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{core: int} |
| core id of the CPU that crashed |
| @item @code{psw-mask: int} |
| control fields of guest PSW |
| @item @code{psw-addr: int} |
| guest instruction address |
| @item @code{reason: S390CrashReason} |
| guest crash reason |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| @section Cryptography |
| |
| |
| @deftp {Enum} QCryptoTLSCredsEndpoint |
| |
| The type of network endpoint that will be using the credentials. |
| Most types of credential require different setup / structures |
| depending on whether they will be used in a server versus a |
| client. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{client} |
| the network endpoint is acting as the client |
| @item @code{server} |
| the network endpoint is acting as the server |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} QCryptoSecretFormat |
| |
| The data format that the secret is provided in |
| |
| @b{Values:} |
| @table @asis |
| @item @code{raw} |
| raw bytes. When encoded in JSON only valid UTF-8 sequences can be used |
| @item @code{base64} |
| arbitrary base64 encoded binary data |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} QCryptoHashAlgorithm |
| |
| The supported algorithms for computing content digests |
| |
| @b{Values:} |
| @table @asis |
| @item @code{md5} |
| MD5. Should not be used in any new code, legacy compat only |
| @item @code{sha1} |
| SHA-1. Should not be used in any new code, legacy compat only |
| @item @code{sha224} |
| SHA-224. (since 2.7) |
| @item @code{sha256} |
| SHA-256. Current recommended strong hash. |
| @item @code{sha384} |
| SHA-384. (since 2.7) |
| @item @code{sha512} |
| SHA-512. (since 2.7) |
| @item @code{ripemd160} |
| RIPEMD-160. (since 2.7) |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} QCryptoCipherAlgorithm |
| |
| The supported algorithms for content encryption ciphers |
| |
| @b{Values:} |
| @table @asis |
| @item @code{aes-128} |
| AES with 128 bit / 16 byte keys |
| @item @code{aes-192} |
| AES with 192 bit / 24 byte keys |
| @item @code{aes-256} |
| AES with 256 bit / 32 byte keys |
| @item @code{des-rfb} |
| RFB specific variant of single DES. Do not use except in VNC. |
| @item @code{3des} |
| 3DES(EDE) with 192 bit / 24 byte keys (since 2.9) |
| @item @code{cast5-128} |
| Cast5 with 128 bit / 16 byte keys |
| @item @code{serpent-128} |
| Serpent with 128 bit / 16 byte keys |
| @item @code{serpent-192} |
| Serpent with 192 bit / 24 byte keys |
| @item @code{serpent-256} |
| Serpent with 256 bit / 32 byte keys |
| @item @code{twofish-128} |
| Twofish with 128 bit / 16 byte keys |
| @item @code{twofish-192} |
| Twofish with 192 bit / 24 byte keys |
| @item @code{twofish-256} |
| Twofish with 256 bit / 32 byte keys |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} QCryptoCipherMode |
| |
| The supported modes for content encryption ciphers |
| |
| @b{Values:} |
| @table @asis |
| @item @code{ecb} |
| Electronic Code Book |
| @item @code{cbc} |
| Cipher Block Chaining |
| @item @code{xts} |
| XEX with tweaked code book and ciphertext stealing |
| @item @code{ctr} |
| Counter (Since 2.8) |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} QCryptoIVGenAlgorithm |
| |
| The supported algorithms for generating initialization |
| vectors for full disk encryption. The 'plain' generator |
| should not be used for disks with sector numbers larger |
| than 2^32, except where compatibility with pre-existing |
| Linux dm-crypt volumes is required. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{plain} |
| 64-bit sector number truncated to 32-bits |
| @item @code{plain64} |
| 64-bit sector number |
| @item @code{essiv} |
| 64-bit sector number encrypted with a hash of the encryption key |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} QCryptoBlockFormat |
| |
| The supported full disk encryption formats |
| |
| @b{Values:} |
| @table @asis |
| @item @code{qcow} |
| QCow/QCow2 built-in AES-CBC encryption. Use only |
| for liberating data from old images. |
| @item @code{luks} |
| LUKS encryption format. Recommended for new images |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockOptionsBase |
| |
| The common options that apply to all full disk |
| encryption formats |
| |
| @b{Members:} |
| @table @asis |
| @item @code{format: QCryptoBlockFormat} |
| the encryption format |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockOptionsQCow |
| |
| The options that apply to QCow/QCow2 AES-CBC encryption format |
| |
| @b{Members:} |
| @table @asis |
| @item @code{key-secret: string} (optional) |
| the ID of a QCryptoSecret object providing the |
| decryption key. Mandatory except when probing image for |
| metadata only. |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockOptionsLUKS |
| |
| The options that apply to LUKS encryption format |
| |
| @b{Members:} |
| @table @asis |
| @item @code{key-secret: string} (optional) |
| the ID of a QCryptoSecret object providing the |
| decryption key. Mandatory except when probing image for |
| metadata only. |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockCreateOptionsLUKS |
| |
| The options that apply to LUKS encryption format initialization |
| |
| @b{Members:} |
| @table @asis |
| @item @code{cipher-alg: QCryptoCipherAlgorithm} (optional) |
| the cipher algorithm for data encryption |
| Currently defaults to 'aes'. |
| @item @code{cipher-mode: QCryptoCipherMode} (optional) |
| the cipher mode for data encryption |
| Currently defaults to 'cbc' |
| @item @code{ivgen-alg: QCryptoIVGenAlgorithm} (optional) |
| the initialization vector generator |
| Currently defaults to 'essiv' |
| @item @code{ivgen-hash-alg: QCryptoHashAlgorithm} (optional) |
| the initialization vector generator hash |
| Currently defaults to 'sha256' |
| @item @code{hash-alg: QCryptoHashAlgorithm} (optional) |
| the master key hash algorithm |
| Currently defaults to 'sha256' |
| @item @code{iter-time: int} (optional) |
| number of milliseconds to spend in |
| PBKDF passphrase processing. Currently defaults |
| to 2000. (since 2.8) |
| @item The members of @code{QCryptoBlockOptionsLUKS} |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockOpenOptions |
| |
| The options that are available for all encryption formats |
| when opening an existing volume |
| |
| @b{Members:} |
| @table @asis |
| @item The members of @code{QCryptoBlockOptionsBase} |
| @item The members of @code{QCryptoBlockOptionsQCow} when @code{format} is @t{"qcow"} |
| @item The members of @code{QCryptoBlockOptionsLUKS} when @code{format} is @t{"luks"} |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockCreateOptions |
| |
| The options that are available for all encryption formats |
| when initializing a new volume |
| |
| @b{Members:} |
| @table @asis |
| @item The members of @code{QCryptoBlockOptionsBase} |
| @item The members of @code{QCryptoBlockOptionsQCow} when @code{format} is @t{"qcow"} |
| @item The members of @code{QCryptoBlockCreateOptionsLUKS} when @code{format} is @t{"luks"} |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockInfoBase |
| |
| The common information that applies to all full disk |
| encryption formats |
| |
| @b{Members:} |
| @table @asis |
| @item @code{format: QCryptoBlockFormat} |
| the encryption format |
| @end table |
| |
| @b{Since:} |
| 2.7 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockInfoLUKSSlot |
| |
| Information about the LUKS block encryption key |
| slot options |
| |
| @b{Members:} |
| @table @asis |
| @item @code{active: boolean} |
| whether the key slot is currently in use |
| @item @code{key-offset: int} |
| offset to the key material in bytes |
| @item @code{iters: int} (optional) |
| number of PBKDF2 iterations for key material |
| @item @code{stripes: int} (optional) |
| number of stripes for splitting key material |
| @end table |
| |
| @b{Since:} |
| 2.7 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockInfoLUKS |
| |
| Information about the LUKS block encryption options |
| |
| @b{Members:} |
| @table @asis |
| @item @code{cipher-alg: QCryptoCipherAlgorithm} |
| the cipher algorithm for data encryption |
| @item @code{cipher-mode: QCryptoCipherMode} |
| the cipher mode for data encryption |
| @item @code{ivgen-alg: QCryptoIVGenAlgorithm} |
| the initialization vector generator |
| @item @code{ivgen-hash-alg: QCryptoHashAlgorithm} (optional) |
| the initialization vector generator hash |
| @item @code{hash-alg: QCryptoHashAlgorithm} |
| the master key hash algorithm |
| @item @code{payload-offset: int} |
| offset to the payload data in bytes |
| @item @code{master-key-iters: int} |
| number of PBKDF2 iterations for key material |
| @item @code{uuid: string} |
| unique identifier for the volume |
| @item @code{slots: array of QCryptoBlockInfoLUKSSlot} |
| information about each key slot |
| @end table |
| |
| @b{Since:} |
| 2.7 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockInfoQCow |
| |
| Information about the QCow block encryption options |
| |
| @b{Since:} |
| 2.7 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} QCryptoBlockInfo |
| |
| Information about the block encryption options |
| |
| @b{Members:} |
| @table @asis |
| @item The members of @code{QCryptoBlockInfoBase} |
| @item The members of @code{QCryptoBlockInfoQCow} when @code{format} is @t{"qcow"} |
| @item The members of @code{QCryptoBlockInfoLUKS} when @code{format} is @t{"luks"} |
| @end table |
| |
| @b{Since:} |
| 2.7 |
| |
| @end deftp |
| |
| |
| @section Block devices |
| |
| @subsection Block core (VM unrelated) |
| |
| |
| @deftp {Object} SnapshotInfo |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{id: string} |
| unique snapshot id |
| @item @code{name: string} |
| user chosen name |
| @item @code{vm-state-size: int} |
| size of the VM state |
| @item @code{date-sec: int} |
| UTC date of the snapshot in seconds |
| @item @code{date-nsec: int} |
| fractional part in nano seconds to be used with date-sec |
| @item @code{vm-clock-sec: int} |
| VM clock relative to boot in seconds |
| @item @code{vm-clock-nsec: int} |
| fractional part in nano seconds to be used with vm-clock-sec |
| @end table |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ImageInfoSpecificQCow2EncryptionBase |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{format: BlockdevQcow2EncryptionFormat} |
| The encryption format |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ImageInfoSpecificQCow2Encryption |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item The members of @code{ImageInfoSpecificQCow2EncryptionBase} |
| @item The members of @code{QCryptoBlockInfoQCow} when @code{format} is @t{"aes"} |
| @item The members of @code{QCryptoBlockInfoLUKS} when @code{format} is @t{"luks"} |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ImageInfoSpecificQCow2 |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{compat: string} |
| compatibility level |
| @item @code{lazy-refcounts: boolean} (optional) |
| on or off; only valid for compat >= 1.1 |
| @item @code{corrupt: boolean} (optional) |
| true if the image has been marked corrupt; only valid for |
| compat >= 1.1 (since 2.2) |
| @item @code{refcount-bits: int} |
| width of a refcount entry in bits (since 2.3) |
| @item @code{encrypt: ImageInfoSpecificQCow2Encryption} (optional) |
| details about encryption parameters; only set if image |
| is encrypted (since 2.10) |
| @end table |
| |
| @b{Since:} |
| 1.7 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ImageInfoSpecificVmdk |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{create-type: string} |
| The create type of VMDK image |
| @item @code{cid: int} |
| Content id of image |
| @item @code{parent-cid: int} |
| Parent VMDK image's cid |
| @item @code{extents: array of ImageInfo} |
| List of extent files |
| @end table |
| |
| @b{Since:} |
| 1.7 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ImageInfoSpecific |
| |
| A discriminated record of image format specific information structures. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type} |
| One of @t{"qcow2"}, @t{"vmdk"}, @t{"luks"} |
| @item @code{data: ImageInfoSpecificQCow2} when @code{type} is @t{"qcow2"} |
| @item @code{data: ImageInfoSpecificVmdk} when @code{type} is @t{"vmdk"} |
| @item @code{data: QCryptoBlockInfoLUKS} when @code{type} is @t{"luks"} |
| @end table |
| |
| @b{Since:} |
| 1.7 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ImageInfo |
| |
| Information about a QEMU image file |
| |
| @b{Members:} |
| @table @asis |
| @item @code{filename: string} |
| name of the image file |
| @item @code{format: string} |
| format of the image file |
| @item @code{virtual-size: int} |
| maximum capacity in bytes of the image |
| @item @code{actual-size: int} (optional) |
| actual size on disk in bytes of the image |
| @item @code{dirty-flag: boolean} (optional) |
| true if image is not cleanly closed |
| @item @code{cluster-size: int} (optional) |
| size of a cluster in bytes |
| @item @code{encrypted: boolean} (optional) |
| true if the image is encrypted |
| @item @code{compressed: boolean} (optional) |
| true if the image is compressed (Since 1.7) |
| @item @code{backing-filename: string} (optional) |
| name of the backing file |
| @item @code{full-backing-filename: string} (optional) |
| full path of the backing file |
| @item @code{backing-filename-format: string} (optional) |
| the format of the backing file |
| @item @code{snapshots: array of SnapshotInfo} (optional) |
| list of VM snapshots |
| @item @code{backing-image: ImageInfo} (optional) |
| info of the backing image (since 1.6) |
| @item @code{format-specific: ImageInfoSpecific} (optional) |
| structure supplying additional format-specific |
| information (since 1.7) |
| @end table |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ImageCheck |
| |
| Information about a QEMU image file check |
| |
| @b{Members:} |
| @table @asis |
| @item @code{filename: string} |
| name of the image file checked |
| @item @code{format: string} |
| format of the image file checked |
| @item @code{check-errors: int} |
| number of unexpected errors occurred during check |
| @item @code{image-end-offset: int} (optional) |
| offset (in bytes) where the image ends, this |
| field is present if the driver for the image format |
| supports it |
| @item @code{corruptions: int} (optional) |
| number of corruptions found during the check if any |
| @item @code{leaks: int} (optional) |
| number of leaks found during the check if any |
| @item @code{corruptions-fixed: int} (optional) |
| number of corruptions fixed during the check |
| if any |
| @item @code{leaks-fixed: int} (optional) |
| number of leaks fixed during the check if any |
| @item @code{total-clusters: int} (optional) |
| total number of clusters, this field is present |
| if the driver for the image format supports it |
| @item @code{allocated-clusters: int} (optional) |
| total number of allocated clusters, this |
| field is present if the driver for the image format |
| supports it |
| @item @code{fragmented-clusters: int} (optional) |
| total number of fragmented clusters, this |
| field is present if the driver for the image format |
| supports it |
| @item @code{compressed-clusters: int} (optional) |
| total number of compressed clusters, this |
| field is present if the driver for the image format |
| supports it |
| @end table |
| |
| @b{Since:} |
| 1.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} MapEntry |
| |
| Mapping information from a virtual block range to a host file range |
| |
| @b{Members:} |
| @table @asis |
| @item @code{start: int} |
| the start byte of the mapped virtual range |
| @item @code{length: int} |
| the number of bytes of the mapped virtual range |
| @item @code{data: boolean} |
| whether the mapped range has data |
| @item @code{zero: boolean} |
| whether the virtual blocks are zeroed |
| @item @code{depth: int} |
| the depth of the mapping |
| @item @code{offset: int} (optional) |
| the offset in file that the virtual sectors are mapped to |
| @item @code{filename: string} (optional) |
| filename that is referred to by @code{offset} |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCacheInfo |
| |
| Cache mode information for a block device |
| |
| @b{Members:} |
| @table @asis |
| @item @code{writeback: boolean} |
| true if writeback mode is enabled |
| @item @code{direct: boolean} |
| true if the host page cache is bypassed (O_DIRECT) |
| @item @code{no-flush: boolean} |
| true if flush requests are ignored for the device |
| @end table |
| |
| @b{Since:} |
| 2.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockDeviceInfo |
| |
| Information about the backing device for a block device. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{file: string} |
| the filename of the backing device |
| @item @code{node-name: string} (optional) |
| the name of the block driver node (Since 2.0) |
| @item @code{ro: boolean} |
| true if the backing device was open read-only |
| @item @code{drv: string} |
| the name of the block format used to open the backing device. As of |
| 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg', |
| 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device', |
| 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', |
| 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' |
| 2.2: 'archipelago' added, 'cow' dropped |
| 2.3: 'host_floppy' deprecated |
| 2.5: 'host_floppy' dropped |
| 2.6: 'luks' added |
| 2.8: 'replication' added, 'tftp' dropped |
| 2.9: 'archipelago' dropped |
| @item @code{backing_file: string} (optional) |
| the name of the backing file (for copy-on-write) |
| @item @code{backing_file_depth: int} |
| number of files in the backing file chain (since: 1.2) |
| @item @code{encrypted: boolean} |
| true if the backing device is encrypted |
| @item @code{encryption_key_missing: boolean} |
| Deprecated; always false |
| @item @code{detect_zeroes: BlockdevDetectZeroesOptions} |
| detect and optimize zero writes (Since 2.1) |
| @item @code{bps: int} |
| total throughput limit in bytes per second is specified |
| @item @code{bps_rd: int} |
| read throughput limit in bytes per second is specified |
| @item @code{bps_wr: int} |
| write throughput limit in bytes per second is specified |
| @item @code{iops: int} |
| total I/O operations per second is specified |
| @item @code{iops_rd: int} |
| read I/O operations per second is specified |
| @item @code{iops_wr: int} |
| write I/O operations per second is specified |
| @item @code{image: ImageInfo} |
| the info of image used (since: 1.6) |
| @item @code{bps_max: int} (optional) |
| total throughput limit during bursts, |
| in bytes (Since 1.7) |
| @item @code{bps_rd_max: int} (optional) |
| read throughput limit during bursts, |
| in bytes (Since 1.7) |
| @item @code{bps_wr_max: int} (optional) |
| write throughput limit during bursts, |
| in bytes (Since 1.7) |
| @item @code{iops_max: int} (optional) |
| total I/O operations per second during bursts, |
| in bytes (Since 1.7) |
| @item @code{iops_rd_max: int} (optional) |
| read I/O operations per second during bursts, |
| in bytes (Since 1.7) |
| @item @code{iops_wr_max: int} (optional) |
| write I/O operations per second during bursts, |
| in bytes (Since 1.7) |
| @item @code{bps_max_length: int} (optional) |
| maximum length of the @code{bps_max} burst |
| period, in seconds. (Since 2.6) |
| @item @code{bps_rd_max_length: int} (optional) |
| maximum length of the @code{bps_rd_max} |
| burst period, in seconds. (Since 2.6) |
| @item @code{bps_wr_max_length: int} (optional) |
| maximum length of the @code{bps_wr_max} |
| burst period, in seconds. (Since 2.6) |
| @item @code{iops_max_length: int} (optional) |
| maximum length of the @code{iops} burst |
| period, in seconds. (Since 2.6) |
| @item @code{iops_rd_max_length: int} (optional) |
| maximum length of the @code{iops_rd_max} |
| burst period, in seconds. (Since 2.6) |
| @item @code{iops_wr_max_length: int} (optional) |
| maximum length of the @code{iops_wr_max} |
| burst period, in seconds. (Since 2.6) |
| @item @code{iops_size: int} (optional) |
| an I/O size in bytes (Since 1.7) |
| @item @code{group: string} (optional) |
| throttle group name (Since 2.4) |
| @item @code{cache: BlockdevCacheInfo} |
| the cache mode used for the block device (since: 2.3) |
| @item @code{write_threshold: int} |
| configured write threshold for the device. |
| 0 if disabled. (Since 2.3) |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockDeviceIoStatus |
| |
| An enumeration of block device I/O status. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{ok} |
| The last I/O operation has succeeded |
| @item @code{failed} |
| The last I/O operation has failed |
| @item @code{nospace} |
| The last I/O operation has failed due to a no-space condition |
| @end table |
| |
| @b{Since:} |
| 1.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockDeviceMapEntry |
| |
| Entry in the metadata map of the device (returned by "qemu-img map") |
| |
| @b{Members:} |
| @table @asis |
| @item @code{start: int} |
| Offset in the image of the first byte described by this entry |
| (in bytes) |
| @item @code{length: int} |
| Length of the range described by this entry (in bytes) |
| @item @code{depth: int} |
| Number of layers (0 = top image, 1 = top image's backing file, etc.) |
| before reaching one for which the range is allocated. The value is |
| in the range 0 to the depth of the image chain - 1. |
| @item @code{zero: boolean} |
| the sectors in this range read as zeros |
| @item @code{data: boolean} |
| reading the image will actually read data from a file (in particular, |
| if @code{offset} is present this means that the sectors are not simply |
| preallocated, but contain actual data in raw format) |
| @item @code{offset: int} (optional) |
| if present, the image file stores the data for this range in |
| raw format at the given offset. |
| @end table |
| |
| @b{Since:} |
| 1.7 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} DirtyBitmapStatus |
| |
| An enumeration of possible states that a dirty bitmap can report to the user. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{frozen} |
| The bitmap is currently in-use by a backup operation or block job, |
| and is immutable. |
| @item @code{disabled} |
| The bitmap is currently in-use by an internal operation and is |
| read-only. It can still be deleted. |
| @item @code{active} |
| The bitmap is actively monitoring for new writes, and can be cleared, |
| deleted, or used for backup operations. |
| @item @code{locked} |
| The bitmap is currently in-use by some operation and can not be |
| cleared, deleted, or used for backup operations. (Since 2.12) |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockDirtyInfo |
| |
| Block dirty bitmap information. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} (optional) |
| the name of the dirty bitmap (Since 2.4) |
| @item @code{count: int} |
| number of dirty bytes according to the dirty bitmap |
| @item @code{granularity: int} |
| granularity of the dirty bitmap in bytes (since 1.4) |
| @item @code{status: DirtyBitmapStatus} |
| current status of the dirty bitmap (since 2.4) |
| @end table |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockLatencyHistogramInfo |
| |
| Block latency histogram. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{boundaries: array of int} |
| list of interval boundary values in nanoseconds, all greater |
| than zero and in ascending order. |
| For example, the list [10, 50, 100] produces the following |
| histogram intervals: [0, 10), [10, 50), [50, 100), [100, +inf). |
| @item @code{bins: array of int} |
| list of io request counts corresponding to histogram intervals. |
| len(@code{bins}) = len(@code{boundaries}) + 1 |
| For the example above, @code{bins} may be something like [3, 1, 5, 2], |
| and corresponding histogram looks like: |
| |
| 5| * |
| 4| * |
| 3| @strong{ } |
| 2| @strong{ } * |
| 1| @strong{ } @strong{ } |
| +------------------ |
| 10 50 100 |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} x-block-latency-histogram-set |
| |
| Manage read, write and flush latency histograms for the device. |
| |
| If only @code{device} parameter is specified, remove all present latency histograms |
| for the device. Otherwise, add/reset some of (or all) latency histograms. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| device name to set latency histogram for. |
| @item @code{boundaries: array of int} (optional) |
| list of interval boundary values (see description in |
| BlockLatencyHistogramInfo definition). If specified, all |
| latency histograms are removed, and empty ones created for all |
| io types with intervals corresponding to @code{boundaries} (except for |
| io types, for which specific boundaries are set through the |
| following parameters). |
| @item @code{boundaries-read: array of int} (optional) |
| list of interval boundary values for read latency |
| histogram. If specified, old read latency histogram is |
| removed, and empty one created with intervals |
| corresponding to @code{boundaries-read}. The parameter has higher |
| priority then @code{boundaries}. |
| @item @code{boundaries-write: array of int} (optional) |
| list of interval boundary values for write latency |
| histogram. |
| @item @code{boundaries-flush: array of int} (optional) |
| list of interval boundary values for flush latency |
| histogram. |
| @end table |
| |
| @b{Returns:} |
| error if device is not found or any boundary arrays are invalid. |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| set new histograms for all io types with intervals |
| [0, 10), [10, 50), [50, 100), [100, +inf): |
| |
| -> @{ "execute": "block-latency-histogram-set", |
| "arguments": @{ "device": "drive0", |
| "boundaries": [10, 50, 100] @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @b{Example:} |
| @example |
| set new histogram only for write, other histograms will remain |
| not changed (or not created): |
| |
| -> @{ "execute": "block-latency-histogram-set", |
| "arguments": @{ "device": "drive0", |
| "boundaries-write": [10, 50, 100] @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @b{Example:} |
| @example |
| set new histograms with the following intervals: |
| read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) |
| write: [0, 1000), [1000, 5000), [5000, +inf) |
| |
| -> @{ "execute": "block-latency-histogram-set", |
| "arguments": @{ "device": "drive0", |
| "boundaries": [10, 50, 100], |
| "boundaries-write": [1000, 5000] @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @b{Example:} |
| @example |
| remove all latency histograms: |
| |
| -> @{ "execute": "block-latency-histogram-set", |
| "arguments": @{ "device": "drive0" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} BlockInfo |
| |
| Block device information. This structure describes a virtual device and |
| the backing device associated with it. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{device: string} |
| The device name associated with the virtual device. |
| @item @code{qdev: string} (optional) |
| The qdev ID, or if no ID is assigned, the QOM path of the block |
| device. (since 2.10) |
| @item @code{type: string} |
| This field is returned only for compatibility reasons, it should |
| not be used (always returns 'unknown') |
| @item @code{removable: boolean} |
| True if the device supports removable media. |
| @item @code{locked: boolean} |
| True if the guest has locked this device from having its media |
| removed |
| @item @code{tray_open: boolean} (optional) |
| True if the device's tray is open |
| (only present if it has a tray) |
| @item @code{dirty-bitmaps: array of BlockDirtyInfo} (optional) |
| dirty bitmaps information (only present if the |
| driver has one or more dirty bitmaps) (Since 2.0) |
| @item @code{io-status: BlockDeviceIoStatus} (optional) |
| @code{BlockDeviceIoStatus}. Only present if the device |
| supports it and the VM is configured to stop on errors |
| (supported device models: virtio-blk, IDE, SCSI except |
| scsi-generic) |
| @item @code{inserted: BlockDeviceInfo} (optional) |
| @code{BlockDeviceInfo} describing the device if media is |
| present |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockMeasureInfo |
| |
| Image file size calculation information. This structure describes the size |
| requirements for creating a new image file. |
| |
| The size requirements depend on the new image file format. File size always |
| equals virtual disk size for the 'raw' format, even for sparse POSIX files. |
| Compact formats such as 'qcow2' represent unallocated and zero regions |
| efficiently so file size may be smaller than virtual disk size. |
| |
| The values are upper bounds that are guaranteed to fit the new image file. |
| Subsequent modification, such as internal snapshot or bitmap creation, may |
| require additional space and is not covered here. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{required: int} |
| Size required for a new image file, in bytes. |
| @item @code{fully-allocated: int} |
| Image file size, in bytes, once data has been written |
| to all sectors. |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-block |
| |
| Get a list of BlockInfo for all virtual block devices. |
| |
| @b{Returns:} |
| a list of @code{BlockInfo} describing each virtual block device. Filter |
| nodes that were created implicitly are skipped over. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-block" @} |
| <- @{ |
| "return":[ |
| @{ |
| "io-status": "ok", |
| "device":"ide0-hd0", |
| "locked":false, |
| "removable":false, |
| "inserted":@{ |
| "ro":false, |
| "drv":"qcow2", |
| "encrypted":false, |
| "file":"disks/test.qcow2", |
| "backing_file_depth":1, |
| "bps":1000000, |
| "bps_rd":0, |
| "bps_wr":0, |
| "iops":1000000, |
| "iops_rd":0, |
| "iops_wr":0, |
| "bps_max": 8000000, |
| "bps_rd_max": 0, |
| "bps_wr_max": 0, |
| "iops_max": 0, |
| "iops_rd_max": 0, |
| "iops_wr_max": 0, |
| "iops_size": 0, |
| "detect_zeroes": "on", |
| "write_threshold": 0, |
| "image":@{ |
| "filename":"disks/test.qcow2", |
| "format":"qcow2", |
| "virtual-size":2048000, |
| "backing_file":"base.qcow2", |
| "full-backing-filename":"disks/base.qcow2", |
| "backing-filename-format":"qcow2", |
| "snapshots":[ |
| @{ |
| "id": "1", |
| "name": "snapshot1", |
| "vm-state-size": 0, |
| "date-sec": 10000200, |
| "date-nsec": 12, |
| "vm-clock-sec": 206, |
| "vm-clock-nsec": 30 |
| @} |
| ], |
| "backing-image":@{ |
| "filename":"disks/base.qcow2", |
| "format":"qcow2", |
| "virtual-size":2048000 |
| @} |
| @} |
| @}, |
| "qdev": "ide_disk", |
| "type":"unknown" |
| @}, |
| @{ |
| "io-status": "ok", |
| "device":"ide1-cd0", |
| "locked":false, |
| "removable":true, |
| "qdev": "/machine/unattached/device[23]", |
| "tray_open": false, |
| "type":"unknown" |
| @}, |
| @{ |
| "device":"floppy0", |
| "locked":false, |
| "removable":true, |
| "qdev": "/machine/unattached/device[20]", |
| "type":"unknown" |
| @}, |
| @{ |
| "device":"sd0", |
| "locked":false, |
| "removable":true, |
| "type":"unknown" |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} BlockDeviceTimedStats |
| |
| Statistics of a block device during a given interval of time. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{interval_length: int} |
| Interval used for calculating the statistics, |
| in seconds. |
| @item @code{min_rd_latency_ns: int} |
| Minimum latency of read operations in the |
| defined interval, in nanoseconds. |
| @item @code{min_wr_latency_ns: int} |
| Minimum latency of write operations in the |
| defined interval, in nanoseconds. |
| @item @code{min_flush_latency_ns: int} |
| Minimum latency of flush operations in the |
| defined interval, in nanoseconds. |
| @item @code{max_rd_latency_ns: int} |
| Maximum latency of read operations in the |
| defined interval, in nanoseconds. |
| @item @code{max_wr_latency_ns: int} |
| Maximum latency of write operations in the |
| defined interval, in nanoseconds. |
| @item @code{max_flush_latency_ns: int} |
| Maximum latency of flush operations in the |
| defined interval, in nanoseconds. |
| @item @code{avg_rd_latency_ns: int} |
| Average latency of read operations in the |
| defined interval, in nanoseconds. |
| @item @code{avg_wr_latency_ns: int} |
| Average latency of write operations in the |
| defined interval, in nanoseconds. |
| @item @code{avg_flush_latency_ns: int} |
| Average latency of flush operations in the |
| defined interval, in nanoseconds. |
| @item @code{avg_rd_queue_depth: number} |
| Average number of pending read operations |
| in the defined interval. |
| @item @code{avg_wr_queue_depth: number} |
| Average number of pending write operations |
| in the defined interval. |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockDeviceStats |
| |
| Statistics of a virtual block device or a block backing device. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{rd_bytes: int} |
| The number of bytes read by the device. |
| @item @code{wr_bytes: int} |
| The number of bytes written by the device. |
| @item @code{rd_operations: int} |
| The number of read operations performed by the device. |
| @item @code{wr_operations: int} |
| The number of write operations performed by the device. |
| @item @code{flush_operations: int} |
| The number of cache flush operations performed by the |
| device (since 0.15.0) |
| @item @code{flush_total_time_ns: int} |
| Total time spend on cache flushes in nano-seconds |
| (since 0.15.0). |
| @item @code{wr_total_time_ns: int} |
| Total time spend on writes in nano-seconds (since 0.15.0). |
| @item @code{rd_total_time_ns: int} |
| Total_time_spend on reads in nano-seconds (since 0.15.0). |
| @item @code{wr_highest_offset: int} |
| The offset after the greatest byte written to the |
| device. The intended use of this information is for |
| growable sparse files (like qcow2) that are used on top |
| of a physical device. |
| @item @code{rd_merged: int} |
| Number of read requests that have been merged into another |
| request (Since 2.3). |
| @item @code{wr_merged: int} |
| Number of write requests that have been merged into another |
| request (Since 2.3). |
| @item @code{idle_time_ns: int} (optional) |
| Time since the last I/O operation, in |
| nanoseconds. If the field is absent it means that |
| there haven't been any operations yet (Since 2.5). |
| @item @code{failed_rd_operations: int} |
| The number of failed read operations |
| performed by the device (Since 2.5) |
| @item @code{failed_wr_operations: int} |
| The number of failed write operations |
| performed by the device (Since 2.5) |
| @item @code{failed_flush_operations: int} |
| The number of failed flush operations |
| performed by the device (Since 2.5) |
| @item @code{invalid_rd_operations: int} |
| The number of invalid read operations |
| performed by the device (Since 2.5) |
| @item @code{invalid_wr_operations: int} |
| The number of invalid write operations |
| performed by the device (Since 2.5) |
| @item @code{invalid_flush_operations: int} |
| The number of invalid flush operations |
| performed by the device (Since 2.5) |
| @item @code{account_invalid: boolean} |
| Whether invalid operations are included in the |
| last access statistics (Since 2.5) |
| @item @code{account_failed: boolean} |
| Whether failed operations are included in the |
| latency and last access statistics (Since 2.5) |
| @item @code{timed_stats: array of BlockDeviceTimedStats} |
| Statistics specific to the set of previously defined |
| intervals of time (Since 2.5) |
| @item @code{x_rd_latency_histogram: BlockLatencyHistogramInfo} (optional) |
| @code{BlockLatencyHistogramInfo}. (Since 2.12) |
| @item @code{x_wr_latency_histogram: BlockLatencyHistogramInfo} (optional) |
| @code{BlockLatencyHistogramInfo}. (Since 2.12) |
| @item @code{x_flush_latency_histogram: BlockLatencyHistogramInfo} (optional) |
| @code{BlockLatencyHistogramInfo}. (Since 2.12) |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockStats |
| |
| Statistics of a virtual block device or a block backing device. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{device: string} (optional) |
| If the stats are for a virtual block device, the name |
| corresponding to the virtual block device. |
| @item @code{node-name: string} (optional) |
| The node name of the device. (Since 2.3) |
| @item @code{stats: BlockDeviceStats} |
| A @code{BlockDeviceStats} for the device. |
| @item @code{parent: BlockStats} (optional) |
| This describes the file block device if it has one. |
| Contains recursively the statistics of the underlying |
| protocol (e.g. the host file for a qcow2 image). If there is |
| no underlying protocol, this field is omitted |
| @item @code{backing: BlockStats} (optional) |
| This describes the backing block device if it has one. |
| (Since 2.0) |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-blockstats |
| |
| Query the @code{BlockStats} for all virtual block devices. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{query-nodes: boolean} (optional) |
| If true, the command will query all the block nodes |
| that have a node name, in a list which will include "parent" |
| information, but not "backing". |
| If false or omitted, the behavior is as before - query all the |
| device backends, recursively including their "parent" and |
| "backing". Filter nodes that were created implicitly are |
| skipped over in this mode. (Since 2.3) |
| @end table |
| |
| @b{Returns:} |
| A list of @code{BlockStats} for each virtual block devices. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-blockstats" @} |
| <- @{ |
| "return":[ |
| @{ |
| "device":"ide0-hd0", |
| "parent":@{ |
| "stats":@{ |
| "wr_highest_offset":3686448128, |
| "wr_bytes":9786368, |
| "wr_operations":751, |
| "rd_bytes":122567168, |
| "rd_operations":36772 |
| "wr_total_times_ns":313253456 |
| "rd_total_times_ns":3465673657 |
| "flush_total_times_ns":49653 |
| "flush_operations":61, |
| "rd_merged":0, |
| "wr_merged":0, |
| "idle_time_ns":2953431879, |
| "account_invalid":true, |
| "account_failed":false |
| @} |
| @}, |
| "stats":@{ |
| "wr_highest_offset":2821110784, |
| "wr_bytes":9786368, |
| "wr_operations":692, |
| "rd_bytes":122739200, |
| "rd_operations":36604 |
| "flush_operations":51, |
| "wr_total_times_ns":313253456 |
| "rd_total_times_ns":3465673657 |
| "flush_total_times_ns":49653, |
| "rd_merged":0, |
| "wr_merged":0, |
| "idle_time_ns":2953431879, |
| "account_invalid":true, |
| "account_failed":false |
| @} |
| @}, |
| @{ |
| "device":"ide1-cd0", |
| "stats":@{ |
| "wr_highest_offset":0, |
| "wr_bytes":0, |
| "wr_operations":0, |
| "rd_bytes":0, |
| "rd_operations":0 |
| "flush_operations":0, |
| "wr_total_times_ns":0 |
| "rd_total_times_ns":0 |
| "flush_total_times_ns":0, |
| "rd_merged":0, |
| "wr_merged":0, |
| "account_invalid":false, |
| "account_failed":false |
| @} |
| @}, |
| @{ |
| "device":"floppy0", |
| "stats":@{ |
| "wr_highest_offset":0, |
| "wr_bytes":0, |
| "wr_operations":0, |
| "rd_bytes":0, |
| "rd_operations":0 |
| "flush_operations":0, |
| "wr_total_times_ns":0 |
| "rd_total_times_ns":0 |
| "flush_total_times_ns":0, |
| "rd_merged":0, |
| "wr_merged":0, |
| "account_invalid":false, |
| "account_failed":false |
| @} |
| @}, |
| @{ |
| "device":"sd0", |
| "stats":@{ |
| "wr_highest_offset":0, |
| "wr_bytes":0, |
| "wr_operations":0, |
| "rd_bytes":0, |
| "rd_operations":0 |
| "flush_operations":0, |
| "wr_total_times_ns":0 |
| "rd_total_times_ns":0 |
| "flush_total_times_ns":0, |
| "rd_merged":0, |
| "wr_merged":0, |
| "account_invalid":false, |
| "account_failed":false |
| @} |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} BlockdevOnError |
| |
| An enumeration of possible behaviors for errors on I/O operations. |
| The exact meaning depends on whether the I/O was initiated by a guest |
| or by a block job |
| |
| @b{Values:} |
| @table @asis |
| @item @code{report} |
| for guest operations, report the error to the guest; |
| for jobs, cancel the job |
| @item @code{ignore} |
| ignore the error, only report a QMP event (BLOCK_IO_ERROR |
| or BLOCK_JOB_ERROR) |
| @item @code{enospc} |
| same as @code{stop} on ENOSPC, same as @code{report} otherwise. |
| @item @code{stop} |
| for guest operations, stop the virtual machine; |
| for jobs, pause the job |
| @item @code{auto} |
| inherit the error handling policy of the backend (since: 2.7) |
| @end table |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} MirrorSyncMode |
| |
| An enumeration of possible behaviors for the initial synchronization |
| phase of storage mirroring. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{top} |
| copies data in the topmost image to the destination |
| @item @code{full} |
| copies data from all images to the destination |
| @item @code{none} |
| only copy data written from now on |
| @item @code{incremental} |
| only copy data described by the dirty bitmap. Since: 2.4 |
| @end table |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockJobType |
| |
| Type of a block job. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{commit} |
| block commit job type, see "block-commit" |
| @item @code{stream} |
| block stream job type, see "block-stream" |
| @item @code{mirror} |
| drive mirror job type, see "drive-mirror" |
| @item @code{backup} |
| drive backup job type, see "drive-backup" |
| @end table |
| |
| @b{Since:} |
| 1.7 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockJobVerb |
| |
| Represents command verbs that can be applied to a blockjob. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{cancel} |
| see @code{block-job-cancel} |
| @item @code{pause} |
| see @code{block-job-pause} |
| @item @code{resume} |
| see @code{block-job-resume} |
| @item @code{set-speed} |
| see @code{block-job-set-speed} |
| @item @code{complete} |
| see @code{block-job-complete} |
| @item @code{dismiss} |
| see @code{block-job-dismiss} |
| @item @code{finalize} |
| see @code{block-job-finalize} |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockJobStatus |
| |
| Indicates the present state of a given blockjob in its lifetime. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{undefined} |
| Erroneous, default state. Should not ever be visible. |
| @item @code{created} |
| The job has been created, but not yet started. |
| @item @code{running} |
| The job is currently running. |
| @item @code{paused} |
| The job is running, but paused. The pause may be requested by |
| either the QMP user or by internal processes. |
| @item @code{ready} |
| The job is running, but is ready for the user to signal completion. |
| This is used for long-running jobs like mirror that are designed to |
| run indefinitely. |
| @item @code{standby} |
| The job is ready, but paused. This is nearly identical to @code{paused}. |
| The job may return to @code{ready} or otherwise be canceled. |
| @item @code{waiting} |
| The job is waiting for other jobs in the transaction to converge |
| to the waiting state. This status will likely not be visible for |
| the last job in a transaction. |
| @item @code{pending} |
| The job has finished its work, but has finalization steps that it |
| needs to make prior to completing. These changes may require |
| manual intervention by the management process if manual was set |
| to true. These changes may still fail. |
| @item @code{aborting} |
| The job is in the process of being aborted, and will finish with |
| an error. The job will afterwards report that it is @code{concluded}. |
| This status may not be visible to the management process. |
| @item @code{concluded} |
| The job has finished all work. If manual was set to true, the job |
| will remain in the query list until it is dismissed. |
| @item @code{null} |
| The job is in the process of being dismantled. This state should not |
| ever be visible externally. |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockJobInfo |
| |
| Information about a long-running block device operation. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: string} |
| the job type ('stream' for image streaming) |
| @item @code{device: string} |
| The job identifier. Originally the device name but other |
| values are allowed since QEMU 2.7 |
| @item @code{len: int} |
| the maximum progress value |
| @item @code{busy: boolean} |
| false if the job is known to be in a quiescent state, with |
| no pending I/O. Since 1.3. |
| @item @code{paused: boolean} |
| whether the job is paused or, if @code{busy} is true, will |
| pause itself as soon as possible. Since 1.3. |
| @item @code{offset: int} |
| the current progress value |
| @item @code{speed: int} |
| the rate limit, bytes per second |
| @item @code{io-status: BlockDeviceIoStatus} |
| the status of the job (since 1.3) |
| @item @code{ready: boolean} |
| true if the job may be completed (since 2.2) |
| @item @code{status: BlockJobStatus} |
| Current job state/status (since 2.12) |
| @item @code{auto-finalize: boolean} |
| Job will finalize itself when PENDING, moving to |
| the CONCLUDED state. (since 2.12) |
| @item @code{auto-dismiss: boolean} |
| Job will dismiss itself when CONCLUDED, moving to the NULL |
| state and disappearing from the query list. (since 2.12) |
| @end table |
| |
| @b{Since:} |
| 1.1 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-block-jobs |
| |
| Return information about long-running block device operations. |
| |
| @b{Returns:} |
| a list of @code{BlockJobInfo} for each active block job |
| |
| @b{Since:} |
| 1.1 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block_passwd |
| |
| This command sets the password of a block device that has not been open |
| with a password and requires one. |
| |
| This command is now obsolete and will always return an error since 2.10 |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} (optional) |
| Not documented |
| @item @code{node-name: string} (optional) |
| Not documented |
| @item @code{password: string} |
| Not documented |
| @end table |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block_resize |
| |
| Resize a block image while a guest is running. |
| |
| Either @code{device} or @code{node-name} must be set but not both. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} (optional) |
| the name of the device to get the image resized |
| @item @code{node-name: string} (optional) |
| graph node name to get the image resized (Since 2.0) |
| @item @code{size: int} |
| new image size in bytes |
| @end table |
| |
| @b{Returns:} |
| nothing on success |
| If @code{device} is not a valid block device, DeviceNotFound |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "block_resize", |
| "arguments": @{ "device": "scratch", "size": 1073741824 @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} NewImageMode |
| |
| An enumeration that tells QEMU how to set the backing file path in |
| a new image file. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{existing} |
| QEMU should look for an existing image file. |
| @item @code{absolute-paths} |
| QEMU should create a new image with absolute paths |
| for the backing file. If there is no backing file available, the new |
| image will not be backed either. |
| @end table |
| |
| @b{Since:} |
| 1.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevSnapshotSync |
| |
| Either @code{device} or @code{node-name} must be set but not both. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{device: string} (optional) |
| the name of the device to generate the snapshot from. |
| @item @code{node-name: string} (optional) |
| graph node name to generate the snapshot from (Since 2.0) |
| @item @code{snapshot-file: string} |
| the target of the new image. If the file exists, or |
| if it is a device, the snapshot will be created in the existing |
| file/device. Otherwise, a new file will be created. |
| @item @code{snapshot-node-name: string} (optional) |
| the graph node name of the new image (Since 2.0) |
| @item @code{format: string} (optional) |
| the format of the snapshot image, default is 'qcow2'. |
| @item @code{mode: NewImageMode} (optional) |
| whether and how QEMU should create a new image, default is |
| 'absolute-paths'. |
| @end table |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevSnapshot |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{node: string} |
| device or node name that will have a snapshot created. |
| @item @code{overlay: string} |
| reference to the existing block device that will become |
| the overlay of @code{node}, as part of creating the snapshot. |
| It must not have a current backing file (this can be |
| achieved by passing "backing": null to blockdev-add). |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} DriveBackup |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{job-id: string} (optional) |
| identifier for the newly-created block job. If |
| omitted, the device name will be used. (Since 2.7) |
| @item @code{device: string} |
| the device name or node-name of a root node which should be copied. |
| @item @code{target: string} |
| the target of the new image. If the file exists, or if it |
| is a device, the existing file/device will be used as the new |
| destination. If it does not exist, a new file will be created. |
| @item @code{format: string} (optional) |
| the format of the new destination, default is to |
| probe if @code{mode} is 'existing', else the format of the source |
| @item @code{sync: MirrorSyncMode} |
| what parts of the disk image should be copied to the destination |
| (all the disk, only the sectors allocated in the topmost image, from a |
| dirty bitmap, or only new I/O). |
| @item @code{mode: NewImageMode} (optional) |
| whether and how QEMU should create a new image, default is |
| 'absolute-paths'. |
| @item @code{speed: int} (optional) |
| the maximum speed, in bytes per second |
| @item @code{bitmap: string} (optional) |
| the name of dirty bitmap if sync is "incremental". |
| Must be present if sync is "incremental", must NOT be present |
| otherwise. (Since 2.4) |
| @item @code{compress: boolean} (optional) |
| true to compress data, if the target format supports it. |
| (default: false) (since 2.8) |
| @item @code{on-source-error: BlockdevOnError} (optional) |
| the action to take on an error on the source, |
| default 'report'. 'stop' and 'enospc' can only be used |
| if the block device supports io-status (see BlockInfo). |
| @item @code{on-target-error: BlockdevOnError} (optional) |
| the action to take on an error on the target, |
| default 'report' (no limitations, since this applies to |
| a different block device than @code{device}). |
| @item @code{auto-finalize: boolean} (optional) |
| When false, this job will wait in a PENDING state after it has |
| finished its work, waiting for @code{block-job-finalize}. |
| When true, this job will automatically perform its abort or |
| commit actions. |
| Defaults to true. (Since 2.12) |
| @item @code{auto-dismiss: boolean} (optional) |
| When false, this job will wait in a CONCLUDED state after it |
| has completed ceased all work, and wait for @code{block-job-dismiss}. |
| When true, this job will automatically disappear from the query |
| list without user intervention. |
| Defaults to true. (Since 2.12) |
| @end table |
| |
| @b{Note:} |
| @code{on-source-error} and @code{on-target-error} only affect background |
| I/O. If an error occurs during a guest write request, the device's |
| rerror/werror actions will be used. |
| |
| @b{Since:} |
| 1.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevBackup |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{job-id: string} (optional) |
| identifier for the newly-created block job. If |
| omitted, the device name will be used. (Since 2.7) |
| @item @code{device: string} |
| the device name or node-name of a root node which should be copied. |
| @item @code{target: string} |
| the device name or node-name of the backup target node. |
| @item @code{sync: MirrorSyncMode} |
| what parts of the disk image should be copied to the destination |
| (all the disk, only the sectors allocated in the topmost image, or |
| only new I/O). |
| @item @code{speed: int} (optional) |
| the maximum speed, in bytes per second. The default is 0, |
| for unlimited. |
| @item @code{compress: boolean} (optional) |
| true to compress data, if the target format supports it. |
| (default: false) (since 2.8) |
| @item @code{on-source-error: BlockdevOnError} (optional) |
| the action to take on an error on the source, |
| default 'report'. 'stop' and 'enospc' can only be used |
| if the block device supports io-status (see BlockInfo). |
| @item @code{on-target-error: BlockdevOnError} (optional) |
| the action to take on an error on the target, |
| default 'report' (no limitations, since this applies to |
| a different block device than @code{device}). |
| @item @code{auto-finalize: boolean} (optional) |
| When false, this job will wait in a PENDING state after it has |
| finished its work, waiting for @code{block-job-finalize}. |
| When true, this job will automatically perform its abort or |
| commit actions. |
| Defaults to true. (Since 2.12) |
| @item @code{auto-dismiss: boolean} (optional) |
| When false, this job will wait in a CONCLUDED state after it |
| has completed ceased all work, and wait for @code{block-job-dismiss}. |
| When true, this job will automatically disappear from the query |
| list without user intervention. |
| Defaults to true. (Since 2.12) |
| @end table |
| |
| @b{Note:} |
| @code{on-source-error} and @code{on-target-error} only affect background |
| I/O. If an error occurs during a guest write request, the device's |
| rerror/werror actions will be used. |
| |
| @b{Since:} |
| 2.3 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} blockdev-snapshot-sync |
| |
| Generates a synchronous snapshot of a block device. |
| |
| For the arguments, see the documentation of BlockdevSnapshotSync. |
| |
| @b{Returns:} |
| nothing on success |
| If @code{device} is not a valid block device, DeviceNotFound |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-snapshot-sync", |
| "arguments": @{ "device": "ide-hd0", |
| "snapshot-file": |
| "/some/place/my-image", |
| "format": "qcow2" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} blockdev-snapshot |
| |
| Generates a snapshot of a block device. |
| |
| Create a snapshot, by installing 'node' as the backing image of |
| 'overlay'. Additionally, if 'node' is associated with a block |
| device, the block device changes to using 'overlay' as its new active |
| image. |
| |
| For the arguments, see the documentation of BlockdevSnapshot. |
| |
| @b{Since:} |
| 2.5 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-add", |
| "arguments": @{ "driver": "qcow2", |
| "node-name": "node1534", |
| "file": @{ "driver": "file", |
| "filename": "hd1.qcow2" @}, |
| "backing": null @} @} |
| |
| <- @{ "return": @{@} @} |
| |
| -> @{ "execute": "blockdev-snapshot", |
| "arguments": @{ "node": "ide-hd0", |
| "overlay": "node1534" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} change-backing-file |
| |
| Change the backing file in the image file metadata. This does not |
| cause QEMU to reopen the image file to reparse the backing filename |
| (it may, however, perform a reopen to change permissions from |
| r/o -> r/w -> r/o, if needed). The new backing file string is written |
| into the image file metadata, and the QEMU internal strings are |
| updated. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{image-node-name: string} |
| The name of the block driver state node of the |
| image to modify. The "device" argument is used |
| to verify "image-node-name" is in the chain |
| described by "device". |
| @item @code{device: string} |
| The device name or node-name of the root node that owns |
| image-node-name. |
| @item @code{backing-file: string} |
| The string to write as the backing file. This |
| string is not validated, so care should be taken |
| when specifying the string or the image chain may |
| not be able to be reopened again. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| If "device" does not exist or cannot be determined, DeviceNotFound |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-commit |
| |
| Live commit of data from overlay image nodes into backing nodes - i.e., |
| writes data between 'top' and 'base' into 'base'. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{job-id: string} (optional) |
| identifier for the newly-created block job. If |
| omitted, the device name will be used. (Since 2.7) |
| @item @code{device: string} |
| the device name or node-name of a root node |
| @item @code{base: string} (optional) |
| The file name of the backing image to write data into. |
| If not specified, this is the deepest backing image. |
| @item @code{top: string} (optional) |
| The file name of the backing image within the image chain, |
| which contains the topmost data to be committed down. If |
| not specified, this is the active layer. |
| @item @code{backing-file: string} (optional) |
| The backing file string to write into the overlay |
| image of 'top'. If 'top' is the active layer, |
| specifying a backing file string is an error. This |
| filename is not validated. |
| |
| If a pathname string is such that it cannot be |
| resolved by QEMU, that means that subsequent QMP or |
| HMP commands must use node-names for the image in |
| question, as filename lookup methods will fail. |
| |
| If not specified, QEMU will automatically determine |
| the backing file string to use, or error out if |
| there is no obvious choice. Care should be taken |
| when specifying the string, to specify a valid |
| filename or protocol. |
| (Since 2.1) |
| |
| If top == base, that is an error. |
| If top == active, the job will not be completed by itself, |
| user needs to complete the job with the block-job-complete |
| command after getting the ready event. (Since 2.0) |
| |
| If the base image is smaller than top, then the base image |
| will be resized to be the same size as top. If top is |
| smaller than the base image, the base will not be |
| truncated. If you want the base image size to match the |
| size of the smaller top, you can safely truncate it |
| yourself once the commit operation successfully completes. |
| @item @code{speed: int} (optional) |
| the maximum speed, in bytes per second |
| @item @code{filter-node-name: string} (optional) |
| the node name that should be assigned to the |
| filter driver that the commit job inserts into the graph |
| above @code{top}. If this option is not given, a node name is |
| autogenerated. (Since: 2.9) |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If commit or stream is already active on this device, DeviceInUse |
| If @code{device} does not exist, DeviceNotFound |
| If image commit is not supported by this device, NotSupported |
| If @code{base} or @code{top} is invalid, a generic error is returned |
| If @code{speed} is invalid, InvalidParameter |
| |
| @b{Since:} |
| 1.3 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "block-commit", |
| "arguments": @{ "device": "virtio0", |
| "top": "/tmp/snap1.qcow2" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} drive-backup |
| |
| Start a point-in-time copy of a block device to a new destination. The |
| status of ongoing drive-backup operations can be checked with |
| query-block-jobs where the BlockJobInfo.type field has the value 'backup'. |
| The operation can be stopped before it has completed using the |
| block-job-cancel command. |
| |
| @b{Arguments:} the members of @code{DriveBackup} |
| |
| @b{Returns:} |
| nothing on success |
| If @code{device} is not a valid block device, GenericError |
| |
| @b{Since:} |
| 1.6 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "drive-backup", |
| "arguments": @{ "device": "drive0", |
| "sync": "full", |
| "target": "backup.img" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} blockdev-backup |
| |
| Start a point-in-time copy of a block device to a new destination. The |
| status of ongoing blockdev-backup operations can be checked with |
| query-block-jobs where the BlockJobInfo.type field has the value 'backup'. |
| The operation can be stopped before it has completed using the |
| block-job-cancel command. |
| |
| @b{Arguments:} the members of @code{BlockdevBackup} |
| |
| @b{Returns:} |
| nothing on success |
| If @code{device} is not a valid block device, DeviceNotFound |
| |
| @b{Since:} |
| 2.3 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-backup", |
| "arguments": @{ "device": "src-id", |
| "sync": "full", |
| "target": "tgt-id" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} query-named-block-nodes |
| |
| Get the named block driver list |
| |
| @b{Returns:} |
| the list of BlockDeviceInfo |
| |
| @b{Since:} |
| 2.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-named-block-nodes" @} |
| <- @{ "return": [ @{ "ro":false, |
| "drv":"qcow2", |
| "encrypted":false, |
| "file":"disks/test.qcow2", |
| "node-name": "my-node", |
| "backing_file_depth":1, |
| "bps":1000000, |
| "bps_rd":0, |
| "bps_wr":0, |
| "iops":1000000, |
| "iops_rd":0, |
| "iops_wr":0, |
| "bps_max": 8000000, |
| "bps_rd_max": 0, |
| "bps_wr_max": 0, |
| "iops_max": 0, |
| "iops_rd_max": 0, |
| "iops_wr_max": 0, |
| "iops_size": 0, |
| "write_threshold": 0, |
| "image":@{ |
| "filename":"disks/test.qcow2", |
| "format":"qcow2", |
| "virtual-size":2048000, |
| "backing_file":"base.qcow2", |
| "full-backing-filename":"disks/base.qcow2", |
| "backing-filename-format":"qcow2", |
| "snapshots":[ |
| @{ |
| "id": "1", |
| "name": "snapshot1", |
| "vm-state-size": 0, |
| "date-sec": 10000200, |
| "date-nsec": 12, |
| "vm-clock-sec": 206, |
| "vm-clock-nsec": 30 |
| @} |
| ], |
| "backing-image":@{ |
| "filename":"disks/base.qcow2", |
| "format":"qcow2", |
| "virtual-size":2048000 |
| @} |
| @} @} ] @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} drive-mirror |
| |
| Start mirroring a block device's writes to a new destination. target |
| specifies the target of the new image. If the file exists, or if it |
| is a device, it will be used as the new destination for writes. If |
| it does not exist, a new file will be created. format specifies the |
| format of the mirror image, default is to probe if mode='existing', |
| else the format of the source. |
| |
| @b{Arguments:} the members of @code{DriveMirror} |
| |
| @b{Returns:} |
| nothing on success |
| If @code{device} is not a valid block device, GenericError |
| |
| @b{Since:} |
| 1.3 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "drive-mirror", |
| "arguments": @{ "device": "ide-hd0", |
| "target": "/some/place/my-image", |
| "sync": "full", |
| "format": "qcow2" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} DriveMirror |
| |
| A set of parameters describing drive mirror setup. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{job-id: string} (optional) |
| identifier for the newly-created block job. If |
| omitted, the device name will be used. (Since 2.7) |
| @item @code{device: string} |
| the device name or node-name of a root node whose writes should be |
| mirrored. |
| @item @code{target: string} |
| the target of the new image. If the file exists, or if it |
| is a device, the existing file/device will be used as the new |
| destination. If it does not exist, a new file will be created. |
| @item @code{format: string} (optional) |
| the format of the new destination, default is to |
| probe if @code{mode} is 'existing', else the format of the source |
| @item @code{node-name: string} (optional) |
| the new block driver state node name in the graph |
| (Since 2.1) |
| @item @code{replaces: string} (optional) |
| with sync=full graph node name to be replaced by the new |
| image when a whole image copy is done. This can be used to repair |
| broken Quorum files. (Since 2.1) |
| @item @code{mode: NewImageMode} (optional) |
| whether and how QEMU should create a new image, default is |
| 'absolute-paths'. |
| @item @code{speed: int} (optional) |
| the maximum speed, in bytes per second |
| @item @code{sync: MirrorSyncMode} |
| what parts of the disk image should be copied to the destination |
| (all the disk, only the sectors allocated in the topmost image, or |
| only new I/O). |
| @item @code{granularity: int} (optional) |
| granularity of the dirty bitmap, default is 64K |
| if the image format doesn't have clusters, 4K if the clusters |
| are smaller than that, else the cluster size. Must be a |
| power of 2 between 512 and 64M (since 1.4). |
| @item @code{buf-size: int} (optional) |
| maximum amount of data in flight from source to |
| target (since 1.4). |
| @item @code{on-source-error: BlockdevOnError} (optional) |
| the action to take on an error on the source, |
| default 'report'. 'stop' and 'enospc' can only be used |
| if the block device supports io-status (see BlockInfo). |
| @item @code{on-target-error: BlockdevOnError} (optional) |
| the action to take on an error on the target, |
| default 'report' (no limitations, since this applies to |
| a different block device than @code{device}). |
| @item @code{unmap: boolean} (optional) |
| Whether to try to unmap target sectors where source has |
| only zero. If true, and target unallocated sectors will read as zero, |
| target image sectors will be unmapped; otherwise, zeroes will be |
| written. Both will result in identical contents. |
| Default is true. (Since 2.4) |
| @end table |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockDirtyBitmap |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{node: string} |
| name of device/node which the bitmap is tracking |
| @item @code{name: string} |
| name of the dirty bitmap |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockDirtyBitmapAdd |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{node: string} |
| name of device/node which the bitmap is tracking |
| @item @code{name: string} |
| name of the dirty bitmap |
| @item @code{granularity: int} (optional) |
| the bitmap granularity, default is 64k for |
| block-dirty-bitmap-add |
| @item @code{persistent: boolean} (optional) |
| the bitmap is persistent, i.e. it will be saved to the |
| corresponding block device image file on its close. For now only |
| Qcow2 disks support persistent bitmaps. Default is false for |
| block-dirty-bitmap-add. (Since: 2.10) |
| @item @code{autoload: boolean} (optional) |
| ignored and deprecated since 2.12. |
| Currently, all dirty tracking bitmaps are loaded from Qcow2 on |
| open. |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} block-dirty-bitmap-add |
| |
| Create a dirty bitmap with a name on the node, and start tracking the writes. |
| |
| @b{Returns:} |
| nothing on success |
| If @code{node} is not a valid block device or node, DeviceNotFound |
| If @code{name} is already taken, GenericError with an explanation |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "block-dirty-bitmap-add", |
| "arguments": @{ "node": "drive0", "name": "bitmap0" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-dirty-bitmap-remove |
| |
| Stop write tracking and remove the dirty bitmap that was created |
| with block-dirty-bitmap-add. If the bitmap is persistent, remove it from its |
| storage too. |
| |
| @b{Returns:} |
| nothing on success |
| If @code{node} is not a valid block device or node, DeviceNotFound |
| If @code{name} is not found, GenericError with an explanation |
| if @code{name} is frozen by an operation, GenericError |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "block-dirty-bitmap-remove", |
| "arguments": @{ "node": "drive0", "name": "bitmap0" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-dirty-bitmap-clear |
| |
| Clear (reset) a dirty bitmap on the device, so that an incremental |
| backup from this point in time forward will only backup clusters |
| modified after this clear operation. |
| |
| @b{Returns:} |
| nothing on success |
| If @code{node} is not a valid block device, DeviceNotFound |
| If @code{name} is not found, GenericError with an explanation |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "block-dirty-bitmap-clear", |
| "arguments": @{ "node": "drive0", "name": "bitmap0" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} BlockDirtyBitmapSha256 |
| |
| SHA256 hash of dirty bitmap data |
| |
| @b{Members:} |
| @table @asis |
| @item @code{sha256: string} |
| ASCII representation of SHA256 bitmap hash |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} x-debug-block-dirty-bitmap-sha256 |
| |
| Get bitmap SHA256 |
| |
| @b{Returns:} |
| BlockDirtyBitmapSha256 on success |
| If @code{node} is not a valid block device, DeviceNotFound |
| If @code{name} is not found or if hashing has failed, GenericError with an |
| explanation |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} blockdev-mirror |
| |
| Start mirroring a block device's writes to a new destination. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{job-id: string} (optional) |
| identifier for the newly-created block job. If |
| omitted, the device name will be used. (Since 2.7) |
| @item @code{device: string} |
| The device name or node-name of a root node whose writes should be |
| mirrored. |
| @item @code{target: string} |
| the id or node-name of the block device to mirror to. This mustn't be |
| attached to guest. |
| @item @code{replaces: string} (optional) |
| with sync=full graph node name to be replaced by the new |
| image when a whole image copy is done. This can be used to repair |
| broken Quorum files. |
| @item @code{speed: int} (optional) |
| the maximum speed, in bytes per second |
| @item @code{sync: MirrorSyncMode} |
| what parts of the disk image should be copied to the destination |
| (all the disk, only the sectors allocated in the topmost image, or |
| only new I/O). |
| @item @code{granularity: int} (optional) |
| granularity of the dirty bitmap, default is 64K |
| if the image format doesn't have clusters, 4K if the clusters |
| are smaller than that, else the cluster size. Must be a |
| power of 2 between 512 and 64M |
| @item @code{buf-size: int} (optional) |
| maximum amount of data in flight from source to |
| target |
| @item @code{on-source-error: BlockdevOnError} (optional) |
| the action to take on an error on the source, |
| default 'report'. 'stop' and 'enospc' can only be used |
| if the block device supports io-status (see BlockInfo). |
| @item @code{on-target-error: BlockdevOnError} (optional) |
| the action to take on an error on the target, |
| default 'report' (no limitations, since this applies to |
| a different block device than @code{device}). |
| @item @code{filter-node-name: string} (optional) |
| the node name that should be assigned to the |
| filter driver that the mirror job inserts into the graph |
| above @code{device}. If this option is not given, a node name is |
| autogenerated. (Since: 2.9) |
| @end table |
| |
| @b{Returns:} |
| nothing on success. |
| |
| @b{Since:} |
| 2.6 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-mirror", |
| "arguments": @{ "device": "ide-hd0", |
| "target": "target0", |
| "sync": "full" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block_set_io_throttle |
| |
| Change I/O throttle limits for a block drive. |
| |
| Since QEMU 2.4, each device with I/O limits is member of a throttle |
| group. |
| |
| If two or more devices are members of the same group, the limits |
| will apply to the combined I/O of the whole group in a round-robin |
| fashion. Therefore, setting new I/O limits to a device will affect |
| the whole group. |
| |
| The name of the group can be specified using the 'group' parameter. |
| If the parameter is unset, it is assumed to be the current group of |
| that device. If it's not in any group yet, the name of the device |
| will be used as the name for its group. |
| |
| The 'group' parameter can also be used to move a device to a |
| different group. In this case the limits specified in the parameters |
| will be applied to the new group only. |
| |
| I/O limits can be disabled by setting all of them to 0. In this case |
| the device will be removed from its group and the rest of its |
| members will not be affected. The 'group' parameter is ignored. |
| |
| @b{Arguments:} the members of @code{BlockIOThrottle} |
| |
| @b{Returns:} |
| Nothing on success |
| If @code{device} is not a valid block device, DeviceNotFound |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "block_set_io_throttle", |
| "arguments": @{ "id": "virtio-blk-pci0/virtio-backend", |
| "bps": 0, |
| "bps_rd": 0, |
| "bps_wr": 0, |
| "iops": 512, |
| "iops_rd": 0, |
| "iops_wr": 0, |
| "bps_max": 0, |
| "bps_rd_max": 0, |
| "bps_wr_max": 0, |
| "iops_max": 0, |
| "iops_rd_max": 0, |
| "iops_wr_max": 0, |
| "bps_max_length": 0, |
| "iops_size": 0 @} @} |
| <- @{ "return": @{@} @} |
| |
| -> @{ "execute": "block_set_io_throttle", |
| "arguments": @{ "id": "ide0-1-0", |
| "bps": 1000000, |
| "bps_rd": 0, |
| "bps_wr": 0, |
| "iops": 0, |
| "iops_rd": 0, |
| "iops_wr": 0, |
| "bps_max": 8000000, |
| "bps_rd_max": 0, |
| "bps_wr_max": 0, |
| "iops_max": 0, |
| "iops_rd_max": 0, |
| "iops_wr_max": 0, |
| "bps_max_length": 60, |
| "iops_size": 0 @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} BlockIOThrottle |
| |
| A set of parameters describing block throttling. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{device: string} (optional) |
| Block device name (deprecated, use @code{id} instead) |
| @item @code{id: string} (optional) |
| The name or QOM path of the guest device (since: 2.8) |
| @item @code{bps: int} |
| total throughput limit in bytes per second |
| @item @code{bps_rd: int} |
| read throughput limit in bytes per second |
| @item @code{bps_wr: int} |
| write throughput limit in bytes per second |
| @item @code{iops: int} |
| total I/O operations per second |
| @item @code{iops_rd: int} |
| read I/O operations per second |
| @item @code{iops_wr: int} |
| write I/O operations per second |
| @item @code{bps_max: int} (optional) |
| total throughput limit during bursts, |
| in bytes (Since 1.7) |
| @item @code{bps_rd_max: int} (optional) |
| read throughput limit during bursts, |
| in bytes (Since 1.7) |
| @item @code{bps_wr_max: int} (optional) |
| write throughput limit during bursts, |
| in bytes (Since 1.7) |
| @item @code{iops_max: int} (optional) |
| total I/O operations per second during bursts, |
| in bytes (Since 1.7) |
| @item @code{iops_rd_max: int} (optional) |
| read I/O operations per second during bursts, |
| in bytes (Since 1.7) |
| @item @code{iops_wr_max: int} (optional) |
| write I/O operations per second during bursts, |
| in bytes (Since 1.7) |
| @item @code{bps_max_length: int} (optional) |
| maximum length of the @code{bps_max} burst |
| period, in seconds. It must only |
| be set if @code{bps_max} is set as well. |
| Defaults to 1. (Since 2.6) |
| @item @code{bps_rd_max_length: int} (optional) |
| maximum length of the @code{bps_rd_max} |
| burst period, in seconds. It must only |
| be set if @code{bps_rd_max} is set as well. |
| Defaults to 1. (Since 2.6) |
| @item @code{bps_wr_max_length: int} (optional) |
| maximum length of the @code{bps_wr_max} |
| burst period, in seconds. It must only |
| be set if @code{bps_wr_max} is set as well. |
| Defaults to 1. (Since 2.6) |
| @item @code{iops_max_length: int} (optional) |
| maximum length of the @code{iops} burst |
| period, in seconds. It must only |
| be set if @code{iops_max} is set as well. |
| Defaults to 1. (Since 2.6) |
| @item @code{iops_rd_max_length: int} (optional) |
| maximum length of the @code{iops_rd_max} |
| burst period, in seconds. It must only |
| be set if @code{iops_rd_max} is set as well. |
| Defaults to 1. (Since 2.6) |
| @item @code{iops_wr_max_length: int} (optional) |
| maximum length of the @code{iops_wr_max} |
| burst period, in seconds. It must only |
| be set if @code{iops_wr_max} is set as well. |
| Defaults to 1. (Since 2.6) |
| @item @code{iops_size: int} (optional) |
| an I/O size in bytes (Since 1.7) |
| @item @code{group: string} (optional) |
| throttle group name (Since 2.4) |
| @end table |
| |
| @b{Since:} |
| 1.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ThrottleLimits |
| |
| Limit parameters for throttling. |
| Since some limit combinations are illegal, limits should always be set in one |
| transaction. All fields are optional. When setting limits, if a field is |
| missing the current value is not changed. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{iops-total: int} (optional) |
| limit total I/O operations per second |
| @item @code{iops-total-max: int} (optional) |
| I/O operations burst |
| @item @code{iops-total-max-length: int} (optional) |
| length of the iops-total-max burst period, in seconds |
| It must only be set if @code{iops-total-max} is set as well. |
| @item @code{iops-read: int} (optional) |
| limit read operations per second |
| @item @code{iops-read-max: int} (optional) |
| I/O operations read burst |
| @item @code{iops-read-max-length: int} (optional) |
| length of the iops-read-max burst period, in seconds |
| It must only be set if @code{iops-read-max} is set as well. |
| @item @code{iops-write: int} (optional) |
| limit write operations per second |
| @item @code{iops-write-max: int} (optional) |
| I/O operations write burst |
| @item @code{iops-write-max-length: int} (optional) |
| length of the iops-write-max burst period, in seconds |
| It must only be set if @code{iops-write-max} is set as well. |
| @item @code{bps-total: int} (optional) |
| limit total bytes per second |
| @item @code{bps-total-max: int} (optional) |
| total bytes burst |
| @item @code{bps-total-max-length: int} (optional) |
| length of the bps-total-max burst period, in seconds. |
| It must only be set if @code{bps-total-max} is set as well. |
| @item @code{bps-read: int} (optional) |
| limit read bytes per second |
| @item @code{bps-read-max: int} (optional) |
| total bytes read burst |
| @item @code{bps-read-max-length: int} (optional) |
| length of the bps-read-max burst period, in seconds |
| It must only be set if @code{bps-read-max} is set as well. |
| @item @code{bps-write: int} (optional) |
| limit write bytes per second |
| @item @code{bps-write-max: int} (optional) |
| total bytes write burst |
| @item @code{bps-write-max-length: int} (optional) |
| length of the bps-write-max burst period, in seconds |
| It must only be set if @code{bps-write-max} is set as well. |
| @item @code{iops-size: int} (optional) |
| when limiting by iops max size of an I/O in bytes |
| @end table |
| |
| @b{Since:} |
| 2.11 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} block-stream |
| |
| Copy data from a backing file into a block device. |
| |
| The block streaming operation is performed in the background until the entire |
| backing file has been copied. This command returns immediately once streaming |
| has started. The status of ongoing block streaming operations can be checked |
| with query-block-jobs. The operation can be stopped before it has completed |
| using the block-job-cancel command. |
| |
| The node that receives the data is called the top image, can be located in |
| any part of the chain (but always above the base image; see below) and can be |
| specified using its device or node name. Earlier qemu versions only allowed |
| 'device' to name the top level node; presence of the 'base-node' parameter |
| during introspection can be used as a witness of the enhanced semantics |
| of 'device'. |
| |
| If a base file is specified then sectors are not copied from that base file and |
| its backing chain. When streaming completes the image file will have the base |
| file as its backing file. This can be used to stream a subset of the backing |
| file chain instead of flattening the entire image. |
| |
| On successful completion the image file is updated to drop the backing file |
| and the BLOCK_JOB_COMPLETED event is emitted. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{job-id: string} (optional) |
| identifier for the newly-created block job. If |
| omitted, the device name will be used. (Since 2.7) |
| @item @code{device: string} |
| the device or node name of the top image |
| @item @code{base: string} (optional) |
| the common backing file name. |
| It cannot be set if @code{base-node} is also set. |
| @item @code{base-node: string} (optional) |
| the node name of the backing file. |
| It cannot be set if @code{base} is also set. (Since 2.8) |
| @item @code{backing-file: string} (optional) |
| The backing file string to write into the top |
| image. This filename is not validated. |
| |
| If a pathname string is such that it cannot be |
| resolved by QEMU, that means that subsequent QMP or |
| HMP commands must use node-names for the image in |
| question, as filename lookup methods will fail. |
| |
| If not specified, QEMU will automatically determine |
| the backing file string to use, or error out if there |
| is no obvious choice. Care should be taken when |
| specifying the string, to specify a valid filename or |
| protocol. |
| (Since 2.1) |
| @item @code{speed: int} (optional) |
| the maximum speed, in bytes per second |
| @item @code{on-error: BlockdevOnError} (optional) |
| the action to take on an error (default report). |
| 'stop' and 'enospc' can only be used if the block device |
| supports io-status (see BlockInfo). Since 1.3. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success. If @code{device} does not exist, DeviceNotFound. |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "block-stream", |
| "arguments": @{ "device": "virtio0", |
| "base": "/tmp/master.qcow2" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-job-set-speed |
| |
| Set maximum speed for a background block operation. |
| |
| This command can only be issued when there is an active block job. |
| |
| Throttling can be disabled by setting the speed to 0. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| The job identifier. This used to be a device name (hence |
| the name of the parameter), but since QEMU 2.7 it can have |
| other values. |
| @item @code{speed: int} |
| the maximum speed, in bytes per second, or 0 for unlimited. |
| Defaults to 0. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If no background operation is active on this device, DeviceNotActive |
| |
| @b{Since:} |
| 1.1 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-job-cancel |
| |
| Stop an active background block operation. |
| |
| This command returns immediately after marking the active background block |
| operation for cancellation. It is an error to call this command if no |
| operation is in progress. |
| |
| The operation will cancel as soon as possible and then emit the |
| BLOCK_JOB_CANCELLED event. Before that happens the job is still visible when |
| enumerated using query-block-jobs. |
| |
| Note that if you issue 'block-job-cancel' after 'drive-mirror' has indicated |
| (via the event BLOCK_JOB_READY) that the source and destination are |
| synchronized, then the event triggered by this command changes to |
| BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the |
| destination now has a point-in-time copy tied to the time of the cancellation. |
| |
| For streaming, the image file retains its backing file unless the streaming |
| operation happens to complete just as it is being cancelled. A new streaming |
| operation can be started at a later time to finish copying all data from the |
| backing file. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| The job identifier. This used to be a device name (hence |
| the name of the parameter), but since QEMU 2.7 it can have |
| other values. |
| @item @code{force: boolean} (optional) |
| If true, and the job has already emitted the event BLOCK_JOB_READY, |
| abandon the job immediately (even if it is paused) instead of waiting |
| for the destination to complete its final synchronization (since 1.3) |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If no background operation is active on this device, DeviceNotActive |
| |
| @b{Since:} |
| 1.1 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-job-pause |
| |
| Pause an active background block operation. |
| |
| This command returns immediately after marking the active background block |
| operation for pausing. It is an error to call this command if no |
| operation is in progress. Pausing an already paused job has no cumulative |
| effect; a single block-job-resume command will resume the job. |
| |
| The operation will pause as soon as possible. No event is emitted when |
| the operation is actually paused. Cancelling a paused job automatically |
| resumes it. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| The job identifier. This used to be a device name (hence |
| the name of the parameter), but since QEMU 2.7 it can have |
| other values. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If no background operation is active on this device, DeviceNotActive |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-job-resume |
| |
| Resume an active background block operation. |
| |
| This command returns immediately after resuming a paused background block |
| operation. It is an error to call this command if no operation is in |
| progress. Resuming an already running job is not an error. |
| |
| This command also clears the error status of the job. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| The job identifier. This used to be a device name (hence |
| the name of the parameter), but since QEMU 2.7 it can have |
| other values. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If no background operation is active on this device, DeviceNotActive |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-job-complete |
| |
| Manually trigger completion of an active background block operation. This |
| is supported for drive mirroring, where it also switches the device to |
| write to the target path only. The ability to complete is signaled with |
| a BLOCK_JOB_READY event. |
| |
| This command completes an active background block operation synchronously. |
| The ordering of this command's return with the BLOCK_JOB_COMPLETED event |
| is not defined. Note that if an I/O error occurs during the processing of |
| this command: 1) the command itself will fail; 2) the error will be processed |
| according to the rerror/werror arguments that were specified when starting |
| the operation. |
| |
| A cancelled or paused job cannot be completed. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| The job identifier. This used to be a device name (hence |
| the name of the parameter), but since QEMU 2.7 it can have |
| other values. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If no background operation is active on this device, DeviceNotActive |
| |
| @b{Since:} |
| 1.3 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-job-dismiss |
| |
| For jobs that have already concluded, remove them from the block-job-query |
| list. This command only needs to be run for jobs which were started with |
| QEMU 2.12+ job lifetime management semantics. |
| |
| This command will refuse to operate on any job that has not yet reached |
| its terminal state, BLOCK_JOB_STATUS_CONCLUDED. For jobs that make use of |
| BLOCK_JOB_READY event, block-job-cancel or block-job-complete will still need |
| to be used as appropriate. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| The job identifier. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-job-finalize |
| |
| Once a job that has manual=true reaches the pending state, it can be |
| instructed to finalize any graph changes and do any necessary cleanup |
| via this command. |
| For jobs in a transaction, instructing one job to finalize will force |
| ALL jobs in the transaction to finalize, so it is only necessary to instruct |
| a single member job to finalize. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| The job identifier. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} BlockdevDiscardOptions |
| |
| Determines how to handle discard requests. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{ignore} |
| Ignore the request |
| @item @code{unmap} |
| Forward as an unmap request |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockdevDetectZeroesOptions |
| |
| Describes the operation mode for the automatic conversion of plain |
| zero writes by the OS to driver specific optimized zero write commands. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{off} |
| Disabled (default) |
| @item @code{on} |
| Enabled |
| @item @code{unmap} |
| Enabled and even try to unmap blocks if possible. This requires |
| also that @code{BlockdevDiscardOptions} is set to unmap for this device. |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockdevAioOptions |
| |
| Selects the AIO backend to handle I/O requests |
| |
| @b{Values:} |
| @table @asis |
| @item @code{threads} |
| Use qemu's thread pool |
| @item @code{native} |
| Use native AIO backend (only Linux and Windows) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCacheOptions |
| |
| Includes cache-related options for block devices |
| |
| @b{Members:} |
| @table @asis |
| @item @code{direct: boolean} (optional) |
| enables use of O_DIRECT (bypass the host page cache; |
| default: false) |
| @item @code{no-flush: boolean} (optional) |
| ignore any flush requests for the device (default: |
| false) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockdevDriver |
| |
| Drivers that are supported in block device operations. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{vxhs} |
| Since 2.10 |
| @item @code{throttle} |
| Since 2.11 |
| @item @code{nvme} |
| Since 2.12 |
| @item @code{blkdebug} |
| Not documented |
| @item @code{blkverify} |
| Not documented |
| @item @code{bochs} |
| Not documented |
| @item @code{cloop} |
| Not documented |
| @item @code{dmg} |
| Not documented |
| @item @code{file} |
| Not documented |
| @item @code{ftp} |
| Not documented |
| @item @code{ftps} |
| Not documented |
| @item @code{gluster} |
| Not documented |
| @item @code{host_cdrom} |
| Not documented |
| @item @code{host_device} |
| Not documented |
| @item @code{http} |
| Not documented |
| @item @code{https} |
| Not documented |
| @item @code{iscsi} |
| Not documented |
| @item @code{luks} |
| Not documented |
| @item @code{nbd} |
| Not documented |
| @item @code{nfs} |
| Not documented |
| @item @code{null-aio} |
| Not documented |
| @item @code{null-co} |
| Not documented |
| @item @code{parallels} |
| Not documented |
| @item @code{qcow} |
| Not documented |
| @item @code{qcow2} |
| Not documented |
| @item @code{qed} |
| Not documented |
| @item @code{quorum} |
| Not documented |
| @item @code{raw} |
| Not documented |
| @item @code{rbd} |
| Not documented |
| @item @code{replication} |
| Not documented |
| @item @code{sheepdog} |
| Not documented |
| @item @code{ssh} |
| Not documented |
| @item @code{vdi} |
| Not documented |
| @item @code{vhdx} |
| Not documented |
| @item @code{vmdk} |
| Not documented |
| @item @code{vpc} |
| Not documented |
| @item @code{vvfat} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsFile |
| |
| Driver specific block device options for the file backend. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{filename: string} |
| path to the image file |
| @item @code{pr-manager: string} (optional) |
| the id for the object that will handle persistent reservations |
| for this device (default: none, forward the commands via SG_IO; |
| since 2.11) |
| @item @code{aio: BlockdevAioOptions} (optional) |
| AIO backend (default: threads) (since: 2.8) |
| @item @code{locking: OnOffAuto} (optional) |
| whether to enable file locking. If set to 'auto', only enable |
| when Open File Descriptor (OFD) locking API is available |
| (default: auto, since 2.10) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsNull |
| |
| Driver specific block device options for the null backend. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{size: int} (optional) |
| size of the device in bytes. |
| @item @code{latency-ns: int} (optional) |
| emulated latency (in nanoseconds) in processing |
| requests. Default to zero which completes requests immediately. |
| (Since 2.4) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsNVMe |
| |
| Driver specific block device options for the NVMe backend. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{device: string} |
| controller address of the NVMe device. |
| @item @code{namespace: int} |
| namespace number of the device, starting from 1. |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsVVFAT |
| |
| Driver specific block device options for the vvfat protocol. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{dir: string} |
| directory to be exported as FAT image |
| @item @code{fat-type: int} (optional) |
| FAT type: 12, 16 or 32 |
| @item @code{floppy: boolean} (optional) |
| whether to export a floppy image (true) or |
| partitioned hard disk (false; default) |
| @item @code{label: string} (optional) |
| set the volume label, limited to 11 bytes. FAT16 and |
| FAT32 traditionally have some restrictions on labels, which are |
| ignored by most operating systems. Defaults to "QEMU VVFAT". |
| (since 2.4) |
| @item @code{rw: boolean} (optional) |
| whether to allow write operations (default: false) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsGenericFormat |
| |
| Driver specific block device options for image format that have no option |
| besides their data source. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{file: BlockdevRef} |
| reference to or definition of the data source block device |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsLUKS |
| |
| Driver specific block device options for LUKS. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{key-secret: string} (optional) |
| the ID of a QCryptoSecret object providing |
| the decryption key (since 2.6). Mandatory except when |
| doing a metadata-only probe of the image. |
| @item The members of @code{BlockdevOptionsGenericFormat} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsGenericCOWFormat |
| |
| Driver specific block device options for image format that have no option |
| besides their data source and an optional backing file. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{backing: BlockdevRefOrNull} (optional) |
| reference to or definition of the backing file block |
| device, null disables the backing file entirely. |
| Defaults to the backing file stored the image file. |
| @item The members of @code{BlockdevOptionsGenericFormat} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} Qcow2OverlapCheckMode |
| |
| General overlap check modes. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{none} |
| Do not perform any checks |
| @item @code{constant} |
| Perform only checks which can be done in constant time and |
| without reading anything from disk |
| @item @code{cached} |
| Perform only checks which can be done without reading anything |
| from disk |
| @item @code{all} |
| Perform all available overlap checks |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} Qcow2OverlapCheckFlags |
| |
| Structure of flags for each metadata structure. Setting a field to 'true' |
| makes qemu guard that structure against unintended overwriting. The default |
| value is chosen according to the template given. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{template: Qcow2OverlapCheckMode} (optional) |
| Specifies a template mode which can be adjusted using the other |
| flags, defaults to 'cached' |
| @item @code{main-header: boolean} (optional) |
| Not documented |
| @item @code{active-l1: boolean} (optional) |
| Not documented |
| @item @code{active-l2: boolean} (optional) |
| Not documented |
| @item @code{refcount-table: boolean} (optional) |
| Not documented |
| @item @code{refcount-block: boolean} (optional) |
| Not documented |
| @item @code{snapshot-table: boolean} (optional) |
| Not documented |
| @item @code{inactive-l1: boolean} (optional) |
| Not documented |
| @item @code{inactive-l2: boolean} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Alternate} Qcow2OverlapChecks |
| |
| Specifies which metadata structures should be guarded against unintended |
| overwriting. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{flags: Qcow2OverlapCheckFlags} |
| set of flags for separate specification of each metadata structure |
| type |
| @item @code{mode: Qcow2OverlapCheckMode} |
| named mode which chooses a specific set of flags |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockdevQcowEncryptionFormat |
| |
| |
| |
| @b{Values:} |
| @table @asis |
| @item @code{aes} |
| AES-CBC with plain64 initialization vectors |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevQcowEncryption |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{format: BlockdevQcowEncryptionFormat} |
| Not documented |
| @item The members of @code{QCryptoBlockOptionsQCow} when @code{format} is @t{"aes"} |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsQcow |
| |
| Driver specific block device options for qcow. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{encrypt: BlockdevQcowEncryption} (optional) |
| Image decryption options. Mandatory for |
| encrypted images, except when doing a metadata-only |
| probe of the image. |
| @item The members of @code{BlockdevOptionsGenericCOWFormat} |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockdevQcow2EncryptionFormat |
| |
| |
| |
| @b{Values:} |
| @table @asis |
| @item @code{aes} |
| AES-CBC with plain64 initialization venctors |
| @item @code{luks} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevQcow2Encryption |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{format: BlockdevQcow2EncryptionFormat} |
| Not documented |
| @item The members of @code{QCryptoBlockOptionsQCow} when @code{format} is @t{"aes"} |
| @item The members of @code{QCryptoBlockOptionsLUKS} when @code{format} is @t{"luks"} |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsQcow2 |
| |
| Driver specific block device options for qcow2. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{lazy-refcounts: boolean} (optional) |
| whether to enable the lazy refcounts |
| feature (default is taken from the image file) |
| @item @code{pass-discard-request: boolean} (optional) |
| whether discard requests to the qcow2 |
| device should be forwarded to the data source |
| @item @code{pass-discard-snapshot: boolean} (optional) |
| whether discard requests for the data source |
| should be issued when a snapshot operation (e.g. |
| deleting a snapshot) frees clusters in the qcow2 file |
| @item @code{pass-discard-other: boolean} (optional) |
| whether discard requests for the data source |
| should be issued on other occasions where a cluster |
| gets freed |
| @item @code{overlap-check: Qcow2OverlapChecks} (optional) |
| which overlap checks to perform for writes |
| to the image, defaults to 'cached' (since 2.2) |
| @item @code{cache-size: int} (optional) |
| the maximum total size of the L2 table and |
| refcount block caches in bytes (since 2.2) |
| @item @code{l2-cache-size: int} (optional) |
| the maximum size of the L2 table cache in |
| bytes (since 2.2) |
| @item @code{l2-cache-entry-size: int} (optional) |
| the size of each entry in the L2 cache in |
| bytes. It must be a power of two between 512 |
| and the cluster size. The default value is |
| the cluster size (since 2.12) |
| @item @code{refcount-cache-size: int} (optional) |
| the maximum size of the refcount block cache |
| in bytes (since 2.2) |
| @item @code{cache-clean-interval: int} (optional) |
| clean unused entries in the L2 and refcount |
| caches. The interval is in seconds. The default value |
| is 0 and it disables this feature (since 2.5) |
| @item @code{encrypt: BlockdevQcow2Encryption} (optional) |
| Image decryption options. Mandatory for |
| encrypted images, except when doing a metadata-only |
| probe of the image. (since 2.10) |
| @item The members of @code{BlockdevOptionsGenericCOWFormat} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} SshHostKeyCheckMode |
| |
| @code{none} Don't check the host key at all |
| @code{hash} Compare the host key with a given hash |
| @code{known_hosts} Check the host key against the known_hosts file |
| |
| @b{Values:} |
| @table @asis |
| @item @code{none} |
| Not documented |
| @item @code{hash} |
| Not documented |
| @item @code{known_hosts} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} SshHostKeyCheckHashType |
| |
| @code{md5} The given hash is an md5 hash |
| @code{sha1} The given hash is an sha1 hash |
| |
| @b{Values:} |
| @table @asis |
| @item @code{md5} |
| Not documented |
| @item @code{sha1} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SshHostKeyHash |
| |
| @code{type} The hash algorithm used for the hash |
| @code{hash} The expected hash value |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: SshHostKeyCheckHashType} |
| Not documented |
| @item @code{hash: string} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SshHostKeyDummy |
| |
| For those union branches that don't need additional fields. |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SshHostKeyCheck |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{mode: SshHostKeyCheckMode} |
| Not documented |
| @item The members of @code{SshHostKeyDummy} when @code{mode} is @t{"none"} |
| @item The members of @code{SshHostKeyHash} when @code{mode} is @t{"hash"} |
| @item The members of @code{SshHostKeyDummy} when @code{mode} is @t{"known_hosts"} |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsSsh |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{server: InetSocketAddress} |
| host address |
| @item @code{path: string} |
| path to the image on the host |
| @item @code{user: string} (optional) |
| user as which to connect, defaults to current |
| local user name |
| @item @code{host-key-check: SshHostKeyCheck} (optional) |
| Defines how and what to check the host key against |
| (default: known_hosts) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlkdebugEvent |
| |
| Trigger events supported by blkdebug. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{l1_shrink_write_table} |
| write zeros to the l1 table to shrink image. |
| (since 2.11) |
| @item @code{l1_shrink_free_l2_clusters} |
| discard the l2 tables. (since 2.11) |
| @item @code{cor_write} |
| a write due to copy-on-read (since 2.11) |
| @item @code{l1_update} |
| Not documented |
| @item @code{l1_grow_alloc_table} |
| Not documented |
| @item @code{l1_grow_write_table} |
| Not documented |
| @item @code{l1_grow_activate_table} |
| Not documented |
| @item @code{l2_load} |
| Not documented |
| @item @code{l2_update} |
| Not documented |
| @item @code{l2_update_compressed} |
| Not documented |
| @item @code{l2_alloc_cow_read} |
| Not documented |
| @item @code{l2_alloc_write} |
| Not documented |
| @item @code{read_aio} |
| Not documented |
| @item @code{read_backing_aio} |
| Not documented |
| @item @code{read_compressed} |
| Not documented |
| @item @code{write_aio} |
| Not documented |
| @item @code{write_compressed} |
| Not documented |
| @item @code{vmstate_load} |
| Not documented |
| @item @code{vmstate_save} |
| Not documented |
| @item @code{cow_read} |
| Not documented |
| @item @code{cow_write} |
| Not documented |
| @item @code{reftable_load} |
| Not documented |
| @item @code{reftable_grow} |
| Not documented |
| @item @code{reftable_update} |
| Not documented |
| @item @code{refblock_load} |
| Not documented |
| @item @code{refblock_update} |
| Not documented |
| @item @code{refblock_update_part} |
| Not documented |
| @item @code{refblock_alloc} |
| Not documented |
| @item @code{refblock_alloc_hookup} |
| Not documented |
| @item @code{refblock_alloc_write} |
| Not documented |
| @item @code{refblock_alloc_write_blocks} |
| Not documented |
| @item @code{refblock_alloc_write_table} |
| Not documented |
| @item @code{refblock_alloc_switch_table} |
| Not documented |
| @item @code{cluster_alloc} |
| Not documented |
| @item @code{cluster_alloc_bytes} |
| Not documented |
| @item @code{cluster_free} |
| Not documented |
| @item @code{flush_to_os} |
| Not documented |
| @item @code{flush_to_disk} |
| Not documented |
| @item @code{pwritev_rmw_head} |
| Not documented |
| @item @code{pwritev_rmw_after_head} |
| Not documented |
| @item @code{pwritev_rmw_tail} |
| Not documented |
| @item @code{pwritev_rmw_after_tail} |
| Not documented |
| @item @code{pwritev} |
| Not documented |
| @item @code{pwritev_zero} |
| Not documented |
| @item @code{pwritev_done} |
| Not documented |
| @item @code{empty_image_prepare} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlkdebugInjectErrorOptions |
| |
| Describes a single error injection for blkdebug. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{event: BlkdebugEvent} |
| trigger event |
| @item @code{state: int} (optional) |
| the state identifier blkdebug needs to be in to |
| actually trigger the event; defaults to "any" |
| @item @code{errno: int} (optional) |
| error identifier (errno) to be returned; defaults to |
| EIO |
| @item @code{sector: int} (optional) |
| specifies the sector index which has to be affected |
| in order to actually trigger the event; defaults to "any |
| sector" |
| @item @code{once: boolean} (optional) |
| disables further events after this one has been |
| triggered; defaults to false |
| @item @code{immediately: boolean} (optional) |
| fail immediately; defaults to false |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlkdebugSetStateOptions |
| |
| Describes a single state-change event for blkdebug. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{event: BlkdebugEvent} |
| trigger event |
| @item @code{state: int} (optional) |
| the current state identifier blkdebug needs to be in; |
| defaults to "any" |
| @item @code{new_state: int} |
| the state identifier blkdebug is supposed to assume if |
| this event is triggered |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsBlkdebug |
| |
| Driver specific block device options for blkdebug. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{image: BlockdevRef} |
| underlying raw block device (or image file) |
| @item @code{config: string} (optional) |
| filename of the configuration file |
| @item @code{align: int} (optional) |
| required alignment for requests in bytes, must be |
| positive power of 2, or 0 for default |
| @item @code{max-transfer: int} (optional) |
| maximum size for I/O transfers in bytes, must be |
| positive multiple of @code{align} and of the underlying |
| file's request alignment (but need not be a power of |
| 2), or 0 for default (since 2.10) |
| @item @code{opt-write-zero: int} (optional) |
| preferred alignment for write zero requests in bytes, |
| must be positive multiple of @code{align} and of the |
| underlying file's request alignment (but need not be a |
| power of 2), or 0 for default (since 2.10) |
| @item @code{max-write-zero: int} (optional) |
| maximum size for write zero requests in bytes, must be |
| positive multiple of @code{align}, of @code{opt-write-zero}, and of |
| the underlying file's request alignment (but need not |
| be a power of 2), or 0 for default (since 2.10) |
| @item @code{opt-discard: int} (optional) |
| preferred alignment for discard requests in bytes, must |
| be positive multiple of @code{align} and of the underlying |
| file's request alignment (but need not be a power of |
| 2), or 0 for default (since 2.10) |
| @item @code{max-discard: int} (optional) |
| maximum size for discard requests in bytes, must be |
| positive multiple of @code{align}, of @code{opt-discard}, and of |
| the underlying file's request alignment (but need not |
| be a power of 2), or 0 for default (since 2.10) |
| @item @code{inject-error: array of BlkdebugInjectErrorOptions} (optional) |
| array of error injection descriptions |
| @item @code{set-state: array of BlkdebugSetStateOptions} (optional) |
| array of state-change descriptions |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsBlkverify |
| |
| Driver specific block device options for blkverify. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{test: BlockdevRef} |
| block device to be tested |
| @item @code{raw: BlockdevRef} |
| raw image used for verification |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} QuorumReadPattern |
| |
| An enumeration of quorum read patterns. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{quorum} |
| read all the children and do a quorum vote on reads |
| @item @code{fifo} |
| read only from the first child that has not failed |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsQuorum |
| |
| Driver specific block device options for Quorum |
| |
| @b{Members:} |
| @table @asis |
| @item @code{blkverify: boolean} (optional) |
| true if the driver must print content mismatch |
| set to false by default |
| @item @code{children: array of BlockdevRef} |
| the children block devices to use |
| @item @code{vote-threshold: int} |
| the vote limit under which a read will fail |
| @item @code{rewrite-corrupted: boolean} (optional) |
| rewrite corrupted data when quorum is reached |
| (Since 2.1) |
| @item @code{read-pattern: QuorumReadPattern} (optional) |
| choose read pattern and set to quorum by default |
| (Since 2.2) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsGluster |
| |
| Driver specific block device options for Gluster |
| |
| @b{Members:} |
| @table @asis |
| @item @code{volume: string} |
| name of gluster volume where VM image resides |
| @item @code{path: string} |
| absolute path to image file in gluster volume |
| @item @code{server: array of SocketAddress} |
| gluster servers description |
| @item @code{debug: int} (optional) |
| libgfapi log level (default '4' which is Error) |
| (Since 2.8) |
| @item @code{logfile: string} (optional) |
| libgfapi log file (default /dev/stderr) (Since 2.8) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} IscsiTransport |
| |
| An enumeration of libiscsi transport types |
| |
| @b{Values:} |
| @table @asis |
| @item @code{tcp} |
| Not documented |
| @item @code{iser} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} IscsiHeaderDigest |
| |
| An enumeration of header digests supported by libiscsi |
| |
| @b{Values:} |
| @table @asis |
| @item @code{crc32c} |
| Not documented |
| @item @code{none} |
| Not documented |
| @item @code{crc32c-none} |
| Not documented |
| @item @code{none-crc32c} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsIscsi |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{transport: IscsiTransport} |
| The iscsi transport type |
| @item @code{portal: string} |
| The address of the iscsi portal |
| @item @code{target: string} |
| The target iqn name |
| @item @code{lun: int} (optional) |
| LUN to connect to. Defaults to 0. |
| @item @code{user: string} (optional) |
| User name to log in with. If omitted, no CHAP |
| authentication is performed. |
| @item @code{password-secret: string} (optional) |
| The ID of a QCryptoSecret object providing |
| the password for the login. This option is required if |
| @code{user} is specified. |
| @item @code{initiator-name: string} (optional) |
| The iqn name we want to identify to the target |
| as. If this option is not specified, an initiator name is |
| generated automatically. |
| @item @code{header-digest: IscsiHeaderDigest} (optional) |
| The desired header digest. Defaults to |
| none-crc32c. |
| @item @code{timeout: int} (optional) |
| Timeout in seconds after which a request will |
| timeout. 0 means no timeout and is the default. |
| @end table |
| Driver specific block device options for iscsi |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsRbd |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{pool: string} |
| Ceph pool name. |
| @item @code{image: string} |
| Image name in the Ceph pool. |
| @item @code{conf: string} (optional) |
| path to Ceph configuration file. Values |
| in the configuration file will be overridden by |
| options specified via QAPI. |
| @item @code{snapshot: string} (optional) |
| Ceph snapshot name. |
| @item @code{user: string} (optional) |
| Ceph id name. |
| @item @code{server: array of InetSocketAddressBase} (optional) |
| Monitor host address and port. This maps |
| to the "mon_host" Ceph option. |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsSheepdog |
| |
| Driver specific block device options for sheepdog |
| |
| @b{Members:} |
| @table @asis |
| @item @code{vdi: string} |
| Virtual disk image name |
| @item @code{server: SocketAddress} |
| The Sheepdog server to connect to |
| @item @code{snap-id: int} (optional) |
| Snapshot ID |
| @item @code{tag: string} (optional) |
| Snapshot tag name |
| @end table |
| Only one of @code{snap-id} and @code{tag} may be present. |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} ReplicationMode |
| |
| An enumeration of replication modes. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{primary} |
| Primary mode, the vm's state will be sent to secondary QEMU. |
| @item @code{secondary} |
| Secondary mode, receive the vm's state from primary QEMU. |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsReplication |
| |
| Driver specific block device options for replication |
| |
| @b{Members:} |
| @table @asis |
| @item @code{mode: ReplicationMode} |
| the replication mode |
| @item @code{top-id: string} (optional) |
| In secondary mode, node name or device ID of the root |
| node who owns the replication node chain. Must not be given in |
| primary mode. |
| @item The members of @code{BlockdevOptionsGenericFormat} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} NFSTransport |
| |
| An enumeration of NFS transport types |
| |
| @b{Values:} |
| @table @asis |
| @item @code{inet} |
| TCP transport |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NFSServer |
| |
| Captures the address of the socket |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: NFSTransport} |
| transport type used for NFS (only TCP supported) |
| @item @code{host: string} |
| host address for NFS server |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsNfs |
| |
| Driver specific block device option for NFS |
| |
| @b{Members:} |
| @table @asis |
| @item @code{server: NFSServer} |
| host address |
| @item @code{path: string} |
| path of the image on the host |
| @item @code{user: int} (optional) |
| UID value to use when talking to the |
| server (defaults to 65534 on Windows and getuid() |
| on unix) |
| @item @code{group: int} (optional) |
| GID value to use when talking to the |
| server (defaults to 65534 on Windows and getgid() |
| in unix) |
| @item @code{tcp-syn-count: int} (optional) |
| number of SYNs during the session |
| establishment (defaults to libnfs default) |
| @item @code{readahead-size: int} (optional) |
| set the readahead size in bytes (defaults |
| to libnfs default) |
| @item @code{page-cache-size: int} (optional) |
| set the pagecache size in bytes (defaults |
| to libnfs default) |
| @item @code{debug: int} (optional) |
| set the NFS debug level (max 2) (defaults |
| to libnfs default) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsCurlBase |
| |
| Driver specific block device options shared by all protocols supported by the |
| curl backend. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{url: string} |
| URL of the image file |
| @item @code{readahead: int} (optional) |
| Size of the read-ahead cache; must be a multiple of |
| 512 (defaults to 256 kB) |
| @item @code{timeout: int} (optional) |
| Timeout for connections, in seconds (defaults to 5) |
| @item @code{username: string} (optional) |
| Username for authentication (defaults to none) |
| @item @code{password-secret: string} (optional) |
| ID of a QCryptoSecret object providing a password |
| for authentication (defaults to no password) |
| @item @code{proxy-username: string} (optional) |
| Username for proxy authentication (defaults to none) |
| @item @code{proxy-password-secret: string} (optional) |
| ID of a QCryptoSecret object providing a password |
| for proxy authentication (defaults to no password) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsCurlHttp |
| |
| Driver specific block device options for HTTP connections over the curl |
| backend. URLs must start with "http://". |
| |
| @b{Members:} |
| @table @asis |
| @item @code{cookie: string} (optional) |
| List of cookies to set; format is |
| "name1=content1; name2=content2;" as explained by |
| CURLOPT_COOKIE(3). Defaults to no cookies. |
| @item @code{cookie-secret: string} (optional) |
| ID of a QCryptoSecret object providing the cookie data in a |
| secure way. See @code{cookie} for the format. (since 2.10) |
| @item The members of @code{BlockdevOptionsCurlBase} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsCurlHttps |
| |
| Driver specific block device options for HTTPS connections over the curl |
| backend. URLs must start with "https://". |
| |
| @b{Members:} |
| @table @asis |
| @item @code{cookie: string} (optional) |
| List of cookies to set; format is |
| "name1=content1; name2=content2;" as explained by |
| CURLOPT_COOKIE(3). Defaults to no cookies. |
| @item @code{sslverify: boolean} (optional) |
| Whether to verify the SSL certificate's validity (defaults to |
| true) |
| @item @code{cookie-secret: string} (optional) |
| ID of a QCryptoSecret object providing the cookie data in a |
| secure way. See @code{cookie} for the format. (since 2.10) |
| @item The members of @code{BlockdevOptionsCurlBase} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsCurlFtp |
| |
| Driver specific block device options for FTP connections over the curl |
| backend. URLs must start with "ftp://". |
| |
| @b{Members:} |
| @table @asis |
| @item The members of @code{BlockdevOptionsCurlBase} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsCurlFtps |
| |
| Driver specific block device options for FTPS connections over the curl |
| backend. URLs must start with "ftps://". |
| |
| @b{Members:} |
| @table @asis |
| @item @code{sslverify: boolean} (optional) |
| Whether to verify the SSL certificate's validity (defaults to |
| true) |
| @item The members of @code{BlockdevOptionsCurlBase} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsNbd |
| |
| Driver specific block device options for NBD. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{server: SocketAddress} |
| NBD server address |
| @item @code{exp: string} (optional) |
| export name |
| @item @code{tls-creds: string} (optional) |
| TLS credentials ID |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsRaw |
| |
| Driver specific block device options for the raw driver. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{offset: int} (optional) |
| position where the block device starts |
| @item @code{size: int} (optional) |
| the assumed size of the device |
| @item The members of @code{BlockdevOptionsGenericFormat} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsVxHS |
| |
| Driver specific block device options for VxHS |
| |
| @b{Members:} |
| @table @asis |
| @item @code{vdisk-id: string} |
| UUID of VxHS volume |
| @item @code{server: InetSocketAddressBase} |
| vxhs server IP, port |
| @item @code{tls-creds: string} (optional) |
| TLS credentials ID |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptionsThrottle |
| |
| Driver specific block device options for the throttle driver |
| |
| @b{Members:} |
| @table @asis |
| @item @code{throttle-group: string} |
| the name of the throttle-group object to use. It |
| must already exist. |
| @item @code{file: BlockdevRef} |
| reference to or definition of the data source block device |
| @end table |
| |
| @b{Since:} |
| 2.11 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevOptions |
| |
| Options for creating a block device. Many options are available for all |
| block devices, independent of the block driver: |
| |
| @b{Members:} |
| @table @asis |
| @item @code{driver: BlockdevDriver} |
| block driver name |
| @item @code{node-name: string} (optional) |
| the node name of the new node (Since 2.0). |
| This option is required on the top level of blockdev-add. |
| @item @code{discard: BlockdevDiscardOptions} (optional) |
| discard-related options (default: ignore) |
| @item @code{cache: BlockdevCacheOptions} (optional) |
| cache-related options |
| @item @code{read-only: boolean} (optional) |
| whether the block device should be read-only (default: false). |
| Note that some block drivers support only read-only access, |
| either generally or in certain configurations. In this case, |
| the default value does not work and the option must be |
| specified explicitly. |
| @item @code{detect-zeroes: BlockdevDetectZeroesOptions} (optional) |
| detect and optimize zero writes (Since 2.1) |
| (default: off) |
| @item @code{force-share: boolean} (optional) |
| force share all permission on added nodes. |
| Requires read-only=true. (Since 2.10) |
| @item The members of @code{BlockdevOptionsBlkdebug} when @code{driver} is @t{"blkdebug"} |
| @item The members of @code{BlockdevOptionsBlkverify} when @code{driver} is @t{"blkverify"} |
| @item The members of @code{BlockdevOptionsGenericFormat} when @code{driver} is @t{"bochs"} |
| @item The members of @code{BlockdevOptionsGenericFormat} when @code{driver} is @t{"cloop"} |
| @item The members of @code{BlockdevOptionsGenericFormat} when @code{driver} is @t{"dmg"} |
| @item The members of @code{BlockdevOptionsFile} when @code{driver} is @t{"file"} |
| @item The members of @code{BlockdevOptionsCurlFtp} when @code{driver} is @t{"ftp"} |
| @item The members of @code{BlockdevOptionsCurlFtps} when @code{driver} is @t{"ftps"} |
| @item The members of @code{BlockdevOptionsGluster} when @code{driver} is @t{"gluster"} |
| @item The members of @code{BlockdevOptionsFile} when @code{driver} is @t{"host_cdrom"} |
| @item The members of @code{BlockdevOptionsFile} when @code{driver} is @t{"host_device"} |
| @item The members of @code{BlockdevOptionsCurlHttp} when @code{driver} is @t{"http"} |
| @item The members of @code{BlockdevOptionsCurlHttps} when @code{driver} is @t{"https"} |
| @item The members of @code{BlockdevOptionsIscsi} when @code{driver} is @t{"iscsi"} |
| @item The members of @code{BlockdevOptionsLUKS} when @code{driver} is @t{"luks"} |
| @item The members of @code{BlockdevOptionsNbd} when @code{driver} is @t{"nbd"} |
| @item The members of @code{BlockdevOptionsNfs} when @code{driver} is @t{"nfs"} |
| @item The members of @code{BlockdevOptionsNull} when @code{driver} is @t{"null-aio"} |
| @item The members of @code{BlockdevOptionsNull} when @code{driver} is @t{"null-co"} |
| @item The members of @code{BlockdevOptionsNVMe} when @code{driver} is @t{"nvme"} |
| @item The members of @code{BlockdevOptionsGenericFormat} when @code{driver} is @t{"parallels"} |
| @item The members of @code{BlockdevOptionsQcow2} when @code{driver} is @t{"qcow2"} |
| @item The members of @code{BlockdevOptionsQcow} when @code{driver} is @t{"qcow"} |
| @item The members of @code{BlockdevOptionsGenericCOWFormat} when @code{driver} is @t{"qed"} |
| @item The members of @code{BlockdevOptionsQuorum} when @code{driver} is @t{"quorum"} |
| @item The members of @code{BlockdevOptionsRaw} when @code{driver} is @t{"raw"} |
| @item The members of @code{BlockdevOptionsRbd} when @code{driver} is @t{"rbd"} |
| @item The members of @code{BlockdevOptionsReplication} when @code{driver} is @t{"replication"} |
| @item The members of @code{BlockdevOptionsSheepdog} when @code{driver} is @t{"sheepdog"} |
| @item The members of @code{BlockdevOptionsSsh} when @code{driver} is @t{"ssh"} |
| @item The members of @code{BlockdevOptionsThrottle} when @code{driver} is @t{"throttle"} |
| @item The members of @code{BlockdevOptionsGenericFormat} when @code{driver} is @t{"vdi"} |
| @item The members of @code{BlockdevOptionsGenericFormat} when @code{driver} is @t{"vhdx"} |
| @item The members of @code{BlockdevOptionsGenericCOWFormat} when @code{driver} is @t{"vmdk"} |
| @item The members of @code{BlockdevOptionsGenericFormat} when @code{driver} is @t{"vpc"} |
| @item The members of @code{BlockdevOptionsVVFAT} when @code{driver} is @t{"vvfat"} |
| @item The members of @code{BlockdevOptionsVxHS} when @code{driver} is @t{"vxhs"} |
| @end table |
| Remaining options are determined by the block driver. |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Alternate} BlockdevRef |
| |
| Reference to a block device. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{definition: BlockdevOptions} |
| defines a new block device inline |
| @item @code{reference: string} |
| references the ID of an existing block device |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Alternate} BlockdevRefOrNull |
| |
| Reference to a block device. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{definition: BlockdevOptions} |
| defines a new block device inline |
| @item @code{reference: string} |
| references the ID of an existing block device. |
| An empty string means that no block device should |
| be referenced. Deprecated; use null instead. |
| @item @code{null: null} |
| No block device should be referenced (since 2.10) |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} blockdev-add |
| |
| Creates a new block device. If the @code{id} option is given at the top level, a |
| BlockBackend will be created; otherwise, @code{node-name} is mandatory at the top |
| level and no BlockBackend will be created. |
| |
| @b{Arguments:} the members of @code{BlockdevOptions} |
| |
| @b{Since:} |
| 2.9 |
| |
| @b{Example:} |
| @example |
| 1. |
| -> @{ "execute": "blockdev-add", |
| "arguments": @{ |
| "driver": "qcow2", |
| "node-name": "test1", |
| "file": @{ |
| "driver": "file", |
| "filename": "test.qcow2" |
| @} |
| @} |
| @} |
| <- @{ "return": @{@} @} |
| |
| 2. |
| -> @{ "execute": "blockdev-add", |
| "arguments": @{ |
| "driver": "qcow2", |
| "node-name": "node0", |
| "discard": "unmap", |
| "cache": @{ |
| "direct": true |
| @}, |
| "file": @{ |
| "driver": "file", |
| "filename": "/tmp/test.qcow2" |
| @}, |
| "backing": @{ |
| "driver": "raw", |
| "file": @{ |
| "driver": "file", |
| "filename": "/dev/fdset/4" |
| @} |
| @} |
| @} |
| @} |
| |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} blockdev-del |
| |
| Deletes a block device that has been added using blockdev-add. |
| The command will fail if the node is attached to a device or is |
| otherwise being used. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{node-name: string} |
| Name of the graph node to delete. |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-add", |
| "arguments": @{ |
| "driver": "qcow2", |
| "node-name": "node0", |
| "file": @{ |
| "driver": "file", |
| "filename": "test.qcow2" |
| @} |
| @} |
| @} |
| <- @{ "return": @{@} @} |
| |
| -> @{ "execute": "blockdev-del", |
| "arguments": @{ "node-name": "node0" @} |
| @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsFile |
| |
| Driver specific image creation options for file. |
| |
| @code{filename} Filename for the new image file |
| @code{size} Size of the virtual disk in bytes |
| @code{preallocation} Preallocation mode for the new image (default: off) |
| @code{nocow} Turn off copy-on-write (valid only on btrfs; default: off) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{filename: string} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{preallocation: PreallocMode} (optional) |
| Not documented |
| @item @code{nocow: boolean} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsGluster |
| |
| Driver specific image creation options for gluster. |
| |
| @code{location} Where to store the new image file |
| @code{size} Size of the virtual disk in bytes |
| @code{preallocation} Preallocation mode for the new image (default: off) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{location: BlockdevOptionsGluster} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{preallocation: PreallocMode} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsLUKS |
| |
| Driver specific image creation options for LUKS. |
| |
| @code{file} Node to create the image format on |
| @code{size} Size of the virtual disk in bytes |
| |
| @b{Members:} |
| @table @asis |
| @item @code{file: BlockdevRef} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item The members of @code{QCryptoBlockCreateOptionsLUKS} |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsNfs |
| |
| Driver specific image creation options for NFS. |
| |
| @code{location} Where to store the new image file |
| @code{size} Size of the virtual disk in bytes |
| |
| @b{Members:} |
| @table @asis |
| @item @code{location: BlockdevOptionsNfs} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsParallels |
| |
| Driver specific image creation options for parallels. |
| |
| @code{file} Node to create the image format on |
| @code{size} Size of the virtual disk in bytes |
| @code{cluster-size} Cluster size in bytes (default: 1 MB) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{file: BlockdevRef} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{cluster-size: int} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsQcow |
| |
| Driver specific image creation options for qcow. |
| |
| @code{file} Node to create the image format on |
| @code{size} Size of the virtual disk in bytes |
| @code{backing-file} File name of the backing file if a backing file |
| should be used |
| @code{encrypt} Encryption options if the image should be encrypted |
| |
| @b{Members:} |
| @table @asis |
| @item @code{file: BlockdevRef} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{backing-file: string} (optional) |
| Not documented |
| @item @code{encrypt: QCryptoBlockCreateOptions} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockdevQcow2Version |
| |
| |
| |
| @b{Values:} |
| @table @asis |
| @item @code{v2} |
| The original QCOW2 format as introduced in qemu 0.10 (version 2) |
| @item @code{v3} |
| The extended QCOW2 format as introduced in qemu 1.1 (version 3) |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsQcow2 |
| |
| Driver specific image creation options for qcow2. |
| |
| @code{file} Node to create the image format on |
| @code{size} Size of the virtual disk in bytes |
| @code{version} Compatibility level (default: v3) |
| @code{backing-file} File name of the backing file if a backing file |
| should be used |
| @code{backing-fmt} Name of the block driver to use for the backing file |
| @code{encrypt} Encryption options if the image should be encrypted |
| @code{cluster-size} qcow2 cluster size in bytes (default: 65536) |
| @code{preallocation} Preallocation mode for the new image (default: off) |
| @code{lazy-refcounts} True if refcounts may be updated lazily (default: off) |
| @code{refcount-bits} Width of reference counts in bits (default: 16) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{file: BlockdevRef} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{version: BlockdevQcow2Version} (optional) |
| Not documented |
| @item @code{backing-file: string} (optional) |
| Not documented |
| @item @code{backing-fmt: BlockdevDriver} (optional) |
| Not documented |
| @item @code{encrypt: QCryptoBlockCreateOptions} (optional) |
| Not documented |
| @item @code{cluster-size: int} (optional) |
| Not documented |
| @item @code{preallocation: PreallocMode} (optional) |
| Not documented |
| @item @code{lazy-refcounts: boolean} (optional) |
| Not documented |
| @item @code{refcount-bits: int} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsQed |
| |
| Driver specific image creation options for qed. |
| |
| @code{file} Node to create the image format on |
| @code{size} Size of the virtual disk in bytes |
| @code{backing-file} File name of the backing file if a backing file |
| should be used |
| @code{backing-fmt} Name of the block driver to use for the backing file |
| @code{cluster-size} Cluster size in bytes (default: 65536) |
| @code{table-size} L1/L2 table size (in clusters) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{file: BlockdevRef} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{backing-file: string} (optional) |
| Not documented |
| @item @code{backing-fmt: BlockdevDriver} (optional) |
| Not documented |
| @item @code{cluster-size: int} (optional) |
| Not documented |
| @item @code{table-size: int} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsRbd |
| |
| Driver specific image creation options for rbd/Ceph. |
| |
| @code{location} Where to store the new image file. This location cannot |
| point to a snapshot. |
| @code{size} Size of the virtual disk in bytes |
| @code{cluster-size} RBD object size |
| |
| @b{Members:} |
| @table @asis |
| @item @code{location: BlockdevOptionsRbd} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{cluster-size: int} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} SheepdogRedundancyType |
| |
| @code{full} Create a fully replicated vdi with x copies |
| @code{erasure-coded} Create an erasure coded vdi with x data strips and |
| y parity strips |
| |
| @b{Values:} |
| @table @asis |
| @item @code{full} |
| Not documented |
| @item @code{erasure-coded} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SheepdogRedundancyFull |
| |
| @code{copies} Number of copies to use (between 1 and 31) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{copies: int} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SheepdogRedundancyErasureCoded |
| |
| @code{data-strips} Number of data strips to use (one of @{2,4,8,16@}) |
| @code{parity-strips} Number of parity strips to use (between 1 and 15) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{data-strips: int} |
| Not documented |
| @item @code{parity-strips: int} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SheepdogRedundancy |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: SheepdogRedundancyType} |
| Not documented |
| @item The members of @code{SheepdogRedundancyFull} when @code{type} is @t{"full"} |
| @item The members of @code{SheepdogRedundancyErasureCoded} when @code{type} is @t{"erasure-coded"} |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsSheepdog |
| |
| Driver specific image creation options for Sheepdog. |
| |
| @code{location} Where to store the new image file |
| @code{size} Size of the virtual disk in bytes |
| @code{backing-file} File name of a base image |
| @code{preallocation} Preallocation mode (allowed values: off, full) |
| @code{redundancy} Redundancy of the image |
| @code{object-size} Object size of the image |
| |
| @b{Members:} |
| @table @asis |
| @item @code{location: BlockdevOptionsSheepdog} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{backing-file: string} (optional) |
| Not documented |
| @item @code{preallocation: PreallocMode} (optional) |
| Not documented |
| @item @code{redundancy: SheepdogRedundancy} (optional) |
| Not documented |
| @item @code{object-size: int} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsSsh |
| |
| Driver specific image creation options for SSH. |
| |
| @code{location} Where to store the new image file |
| @code{size} Size of the virtual disk in bytes |
| |
| @b{Members:} |
| @table @asis |
| @item @code{location: BlockdevOptionsSsh} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsVdi |
| |
| Driver specific image creation options for VDI. |
| |
| @code{file} Node to create the image format on |
| @code{size} Size of the virtual disk in bytes |
| @code{preallocation} Preallocation mode for the new image (allowed values: off, |
| metadata; default: off) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{file: BlockdevRef} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{preallocation: PreallocMode} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockdevVhdxSubformat |
| |
| |
| |
| @b{Values:} |
| @table @asis |
| @item @code{dynamic} |
| Growing image file |
| @item @code{fixed} |
| Preallocated fixed-size image file |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsVhdx |
| |
| Driver specific image creation options for vhdx. |
| |
| @code{file} Node to create the image format on |
| @code{size} Size of the virtual disk in bytes |
| @code{log-size} Log size in bytes, must be a multiple of 1 MB |
| (default: 1 MB) |
| @code{block-size} Block size in bytes, must be a multiple of 1 MB and not |
| larger than 256 MB (default: automatically choose a block |
| size depending on the image size) |
| @code{subformat} vhdx subformat (default: dynamic) |
| @code{block-state-zero} Force use of payload blocks of type 'ZERO'. Non-standard, |
| but default. Do not set to 'off' when using 'qemu-img |
| convert' with subformat=dynamic. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{file: BlockdevRef} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{log-size: int} (optional) |
| Not documented |
| @item @code{block-size: int} (optional) |
| Not documented |
| @item @code{subformat: BlockdevVhdxSubformat} (optional) |
| Not documented |
| @item @code{block-state-zero: boolean} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} BlockdevVpcSubformat |
| |
| |
| |
| @b{Values:} |
| @table @asis |
| @item @code{dynamic} |
| Growing image file |
| @item @code{fixed} |
| Preallocated fixed-size image file |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptionsVpc |
| |
| Driver specific image creation options for vpc (VHD). |
| |
| @code{file} Node to create the image format on |
| @code{size} Size of the virtual disk in bytes |
| @code{subformat} vhdx subformat (default: dynamic) |
| @code{force-size} Force use of the exact byte size instead of rounding to the |
| next size that can be represented in CHS geometry |
| (default: false) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{file: BlockdevRef} |
| Not documented |
| @item @code{size: int} |
| Not documented |
| @item @code{subformat: BlockdevVpcSubformat} (optional) |
| Not documented |
| @item @code{force-size: boolean} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateNotSupported |
| |
| This is used for all drivers that don't support creating images. |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevCreateOptions |
| |
| Options for creating an image format on a given node. |
| |
| @code{driver} block driver to create the image format |
| |
| @b{Members:} |
| @table @asis |
| @item @code{driver: BlockdevDriver} |
| Not documented |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"blkdebug"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"blkverify"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"bochs"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"cloop"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"dmg"} |
| @item The members of @code{BlockdevCreateOptionsFile} when @code{driver} is @t{"file"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"ftp"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"ftps"} |
| @item The members of @code{BlockdevCreateOptionsGluster} when @code{driver} is @t{"gluster"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"host_cdrom"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"host_device"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"http"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"https"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"iscsi"} |
| @item The members of @code{BlockdevCreateOptionsLUKS} when @code{driver} is @t{"luks"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"nbd"} |
| @item The members of @code{BlockdevCreateOptionsNfs} when @code{driver} is @t{"nfs"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"null-aio"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"null-co"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"nvme"} |
| @item The members of @code{BlockdevCreateOptionsParallels} when @code{driver} is @t{"parallels"} |
| @item The members of @code{BlockdevCreateOptionsQcow} when @code{driver} is @t{"qcow"} |
| @item The members of @code{BlockdevCreateOptionsQcow2} when @code{driver} is @t{"qcow2"} |
| @item The members of @code{BlockdevCreateOptionsQed} when @code{driver} is @t{"qed"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"quorum"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"raw"} |
| @item The members of @code{BlockdevCreateOptionsRbd} when @code{driver} is @t{"rbd"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"replication"} |
| @item The members of @code{BlockdevCreateOptionsSheepdog} when @code{driver} is @t{"sheepdog"} |
| @item The members of @code{BlockdevCreateOptionsSsh} when @code{driver} is @t{"ssh"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"throttle"} |
| @item The members of @code{BlockdevCreateOptionsVdi} when @code{driver} is @t{"vdi"} |
| @item The members of @code{BlockdevCreateOptionsVhdx} when @code{driver} is @t{"vhdx"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"vmdk"} |
| @item The members of @code{BlockdevCreateOptionsVpc} when @code{driver} is @t{"vpc"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"vvfat"} |
| @item The members of @code{BlockdevCreateNotSupported} when @code{driver} is @t{"vxhs"} |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} x-blockdev-create |
| |
| Create an image format on a given node. |
| TODO Replace with something asynchronous (block job?) |
| |
| @b{Arguments:} the members of @code{BlockdevCreateOptions} |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} blockdev-open-tray |
| |
| Opens a block device's tray. If there is a block driver state tree inserted as |
| a medium, it will become inaccessible to the guest (but it will remain |
| associated to the block device, so closing the tray will make it accessible |
| again). |
| |
| If the tray was already open before, this will be a no-op. |
| |
| Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in |
| which no such event will be generated, these include: |
| @itemize @minus |
| @item |
| if the guest has locked the tray, @code{force} is false and the guest does not |
| respond to the eject request |
| @item |
| if the BlockBackend denoted by @code{device} does not have a guest device attached |
| to it |
| @item |
| if the guest device does not have an actual tray |
| @end itemize |
| |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} (optional) |
| Block device name (deprecated, use @code{id} instead) |
| @item @code{id: string} (optional) |
| The name or QOM path of the guest device (since: 2.8) |
| @item @code{force: boolean} (optional) |
| if false (the default), an eject request will be sent to |
| the guest if it has locked the tray (and the tray will not be opened |
| immediately); if true, the tray will be opened regardless of whether |
| it is locked |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-open-tray", |
| "arguments": @{ "id": "ide0-1-0" @} @} |
| |
| <- @{ "timestamp": @{ "seconds": 1418751016, |
| "microseconds": 716996 @}, |
| "event": "DEVICE_TRAY_MOVED", |
| "data": @{ "device": "ide1-cd0", |
| "id": "ide0-1-0", |
| "tray-open": true @} @} |
| |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} blockdev-close-tray |
| |
| Closes a block device's tray. If there is a block driver state tree associated |
| with the block device (which is currently ejected), that tree will be loaded |
| as the medium. |
| |
| If the tray was already closed before, this will be a no-op. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} (optional) |
| Block device name (deprecated, use @code{id} instead) |
| @item @code{id: string} (optional) |
| The name or QOM path of the guest device (since: 2.8) |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-close-tray", |
| "arguments": @{ "id": "ide0-1-0" @} @} |
| |
| <- @{ "timestamp": @{ "seconds": 1418751345, |
| "microseconds": 272147 @}, |
| "event": "DEVICE_TRAY_MOVED", |
| "data": @{ "device": "ide1-cd0", |
| "id": "ide0-1-0", |
| "tray-open": false @} @} |
| |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} blockdev-remove-medium |
| |
| Removes a medium (a block driver state tree) from a block device. That block |
| device's tray must currently be open (unless there is no attached guest |
| device). |
| |
| If the tray is open and there is no medium inserted, this will be a no-op. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| The name or QOM path of the guest device |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-remove-medium", |
| "arguments": @{ "id": "ide0-1-0" @} @} |
| |
| <- @{ "error": @{ "class": "GenericError", |
| "desc": "Tray of device 'ide0-1-0' is not open" @} @} |
| |
| -> @{ "execute": "blockdev-open-tray", |
| "arguments": @{ "id": "ide0-1-0" @} @} |
| |
| <- @{ "timestamp": @{ "seconds": 1418751627, |
| "microseconds": 549958 @}, |
| "event": "DEVICE_TRAY_MOVED", |
| "data": @{ "device": "ide1-cd0", |
| "id": "ide0-1-0", |
| "tray-open": true @} @} |
| |
| <- @{ "return": @{@} @} |
| |
| -> @{ "execute": "blockdev-remove-medium", |
| "arguments": @{ "id": "ide0-1-0" @} @} |
| |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} blockdev-insert-medium |
| |
| Inserts a medium (a block driver state tree) into a block device. That block |
| device's tray must currently be open (unless there is no attached guest |
| device) and there must be no medium inserted already. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| The name or QOM path of the guest device |
| @item @code{node-name: string} |
| name of a node in the block driver state graph |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-add", |
| "arguments": @{ |
| "node-name": "node0", |
| "driver": "raw", |
| "file": @{ "driver": "file", |
| "filename": "fedora.iso" @} @} @} |
| <- @{ "return": @{@} @} |
| |
| -> @{ "execute": "blockdev-insert-medium", |
| "arguments": @{ "id": "ide0-1-0", |
| "node-name": "node0" @} @} |
| |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} BlockdevChangeReadOnlyMode |
| |
| Specifies the new read-only mode of a block device subject to the |
| @code{blockdev-change-medium} command. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{retain} |
| Retains the current read-only mode |
| @item @code{read-only} |
| Makes the device read-only |
| @item @code{read-write} |
| Makes the device writable |
| @end table |
| |
| @b{Since:} |
| 2.3 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} blockdev-change-medium |
| |
| Changes the medium inserted into a block device by ejecting the current medium |
| and loading a new image file which is inserted as the new medium (this command |
| combines blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium |
| and blockdev-close-tray). |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} (optional) |
| Block device name (deprecated, use @code{id} instead) |
| @item @code{id: string} (optional) |
| The name or QOM path of the guest device |
| (since: 2.8) |
| @item @code{filename: string} |
| filename of the new image to be loaded |
| @item @code{format: string} (optional) |
| format to open the new image with (defaults to |
| the probed format) |
| @item @code{read-only-mode: BlockdevChangeReadOnlyMode} (optional) |
| change the read-only mode of the device; defaults |
| to 'retain' |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @b{Examples:} |
| @example |
| 1. Change a removable medium |
| |
| -> @{ "execute": "blockdev-change-medium", |
| "arguments": @{ "id": "ide0-1-0", |
| "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", |
| "format": "raw" @} @} |
| <- @{ "return": @{@} @} |
| |
| 2. Load a read-only medium into a writable drive |
| |
| -> @{ "execute": "blockdev-change-medium", |
| "arguments": @{ "id": "floppyA", |
| "filename": "/srv/images/ro.img", |
| "format": "raw", |
| "read-only-mode": "retain" @} @} |
| |
| <- @{ "error": |
| @{ "class": "GenericError", |
| "desc": "Could not open '/srv/images/ro.img': Permission denied" @} @} |
| |
| -> @{ "execute": "blockdev-change-medium", |
| "arguments": @{ "id": "floppyA", |
| "filename": "/srv/images/ro.img", |
| "format": "raw", |
| "read-only-mode": "read-only" @} @} |
| |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} BlockErrorAction |
| |
| An enumeration of action that has been taken when a DISK I/O occurs |
| |
| @b{Values:} |
| @table @asis |
| @item @code{ignore} |
| error has been ignored |
| @item @code{report} |
| error has been reported to the device |
| @item @code{stop} |
| error caused VM to be stopped |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Event {} BLOCK_IMAGE_CORRUPTED |
| |
| Emitted when a disk image is being marked corrupt. The image can be |
| identified by its device or node name. The 'device' field is always |
| present for compatibility reasons, but it can be empty ("") if the |
| image does not have a device name associated. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| device name. This is always present for compatibility |
| reasons, but it can be empty ("") if the image does not |
| have a device name associated. |
| @item @code{node-name: string} (optional) |
| node name (Since: 2.4) |
| @item @code{msg: string} |
| informative message for human consumption, such as the kind of |
| corruption being detected. It should not be parsed by machine as it is |
| not guaranteed to be stable |
| @item @code{offset: int} (optional) |
| if the corruption resulted from an image access, this is |
| the host's access offset into the image |
| @item @code{size: int} (optional) |
| if the corruption resulted from an image access, this is |
| the access size |
| @item @code{fatal: boolean} |
| if set, the image is marked corrupt and therefore unusable after this |
| event and must be repaired (Since 2.2; before, every |
| BLOCK_IMAGE_CORRUPTED event was fatal) |
| @end table |
| |
| @b{Note:} |
| If action is "stop", a STOP event will eventually follow the |
| BLOCK_IO_ERROR event. |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "BLOCK_IMAGE_CORRUPTED", |
| "data": @{ "device": "ide0-hd0", "node-name": "node0", |
| "msg": "Prevented active L1 table overwrite", "offset": 196608, |
| "size": 65536 @}, |
| "timestamp": @{ "seconds": 1378126126, "microseconds": 966463 @} @} |
| @end example |
| |
| @b{Since:} |
| 1.7 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} BLOCK_IO_ERROR |
| |
| Emitted when a disk I/O error occurs |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| device name. This is always present for compatibility |
| reasons, but it can be empty ("") if the image does not |
| have a device name associated. |
| @item @code{node-name: string} (optional) |
| node name. Note that errors may be reported for the root node |
| that is directly attached to a guest device rather than for the |
| node where the error occurred. The node name is not present if |
| the drive is empty. (Since: 2.8) |
| @item @code{operation: IoOperationType} |
| I/O operation |
| @item @code{action: BlockErrorAction} |
| action that has been taken |
| @item @code{nospace: boolean} (optional) |
| true if I/O error was caused due to a no-space |
| condition. This key is only present if query-block's |
| io-status is present, please see query-block documentation |
| for more information (since: 2.2) |
| @item @code{reason: string} |
| human readable string describing the error cause. |
| (This field is a debugging aid for humans, it should not |
| be parsed by applications) (since: 2.2) |
| @end table |
| |
| @b{Note:} |
| If action is "stop", a STOP event will eventually follow the |
| BLOCK_IO_ERROR event |
| |
| @b{Since:} |
| 0.13.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "BLOCK_IO_ERROR", |
| "data": @{ "device": "ide0-hd1", |
| "node-name": "#block212", |
| "operation": "write", |
| "action": "stop" @}, |
| "timestamp": @{ "seconds": 1265044230, "microseconds": 450486 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} BLOCK_JOB_COMPLETED |
| |
| Emitted when a block job has completed |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{type: BlockJobType} |
| job type |
| @item @code{device: string} |
| The job identifier. Originally the device name but other |
| values are allowed since QEMU 2.7 |
| @item @code{len: int} |
| maximum progress value |
| @item @code{offset: int} |
| current progress value. On success this is equal to len. |
| On failure this is less than len |
| @item @code{speed: int} |
| rate limit, bytes per second |
| @item @code{error: string} (optional) |
| error message. Only present on failure. This field |
| contains a human-readable error message. There are no semantics |
| other than that streaming has failed and clients should not try to |
| interpret the error string |
| @end table |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "BLOCK_JOB_COMPLETED", |
| "data": @{ "type": "stream", "device": "virtio-disk0", |
| "len": 10737418240, "offset": 10737418240, |
| "speed": 0 @}, |
| "timestamp": @{ "seconds": 1267061043, "microseconds": 959568 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} BLOCK_JOB_CANCELLED |
| |
| Emitted when a block job has been cancelled |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{type: BlockJobType} |
| job type |
| @item @code{device: string} |
| The job identifier. Originally the device name but other |
| values are allowed since QEMU 2.7 |
| @item @code{len: int} |
| maximum progress value |
| @item @code{offset: int} |
| current progress value. On success this is equal to len. |
| On failure this is less than len |
| @item @code{speed: int} |
| rate limit, bytes per second |
| @end table |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "BLOCK_JOB_CANCELLED", |
| "data": @{ "type": "stream", "device": "virtio-disk0", |
| "len": 10737418240, "offset": 134217728, |
| "speed": 0 @}, |
| "timestamp": @{ "seconds": 1267061043, "microseconds": 959568 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} BLOCK_JOB_ERROR |
| |
| Emitted when a block job encounters an error |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| The job identifier. Originally the device name but other |
| values are allowed since QEMU 2.7 |
| @item @code{operation: IoOperationType} |
| I/O operation |
| @item @code{action: BlockErrorAction} |
| action that has been taken |
| @end table |
| |
| @b{Since:} |
| 1.3 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "BLOCK_JOB_ERROR", |
| "data": @{ "device": "ide0-hd1", |
| "operation": "write", |
| "action": "stop" @}, |
| "timestamp": @{ "seconds": 1265044230, "microseconds": 450486 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} BLOCK_JOB_READY |
| |
| Emitted when a block job is ready to complete |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{type: BlockJobType} |
| job type |
| @item @code{device: string} |
| The job identifier. Originally the device name but other |
| values are allowed since QEMU 2.7 |
| @item @code{len: int} |
| maximum progress value |
| @item @code{offset: int} |
| current progress value. On success this is equal to len. |
| On failure this is less than len |
| @item @code{speed: int} |
| rate limit, bytes per second |
| @end table |
| |
| @b{Note:} |
| The "ready to complete" status is always reset by a @code{BLOCK_JOB_ERROR} |
| event |
| |
| @b{Since:} |
| 1.3 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "BLOCK_JOB_READY", |
| "data": @{ "device": "drive0", "type": "mirror", "speed": 0, |
| "len": 2097152, "offset": 2097152 @} |
| "timestamp": @{ "seconds": 1265044230, "microseconds": 450486 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} BLOCK_JOB_PENDING |
| |
| Emitted when a block job is awaiting explicit authorization to finalize graph |
| changes via @code{block-job-finalize}. If this job is part of a transaction, it will |
| not emit this event until the transaction has converged first. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{type: BlockJobType} |
| job type |
| @item @code{id: string} |
| The job identifier. |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "BLOCK_JOB_WAITING", |
| "data": @{ "device": "drive0", "type": "mirror" @}, |
| "timestamp": @{ "seconds": 1265044230, "microseconds": 450486 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} PreallocMode |
| |
| Preallocation mode of QEMU image file |
| |
| @b{Values:} |
| @table @asis |
| @item @code{off} |
| no preallocation |
| @item @code{metadata} |
| preallocate only for metadata |
| @item @code{falloc} |
| like @code{full} preallocation but allocate disk space by |
| posix_fallocate() rather than writing zeros. |
| @item @code{full} |
| preallocate all data by writing zeros to device to ensure disk |
| space is really available. @code{full} preallocation also sets up |
| metadata correctly. |
| @end table |
| |
| @b{Since:} |
| 2.2 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Event {} BLOCK_WRITE_THRESHOLD |
| |
| Emitted when writes on block device reaches or exceeds the |
| configured write threshold. For thin-provisioned devices, this |
| means the device should be extended to avoid pausing for |
| disk exhaustion. |
| The event is one shot. Once triggered, it needs to be |
| re-registered with another block-set-write-threshold command. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{node-name: string} |
| graph node name on which the threshold was exceeded. |
| @item @code{amount-exceeded: int} |
| amount of data which exceeded the threshold, in bytes. |
| @item @code{write-threshold: int} |
| last configured threshold, in bytes. |
| @end table |
| |
| @b{Since:} |
| 2.3 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} block-set-write-threshold |
| |
| Change the write threshold for a block drive. An event will be |
| delivered if a write to this block drive crosses the configured |
| threshold. The threshold is an offset, thus must be |
| non-negative. Default is no write threshold. Setting the threshold |
| to zero disables it. |
| |
| This is useful to transparently resize thin-provisioned drives without |
| the guest OS noticing. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{node-name: string} |
| graph node name on which the threshold must be set. |
| @item @code{write-threshold: int} |
| configured threshold for the block device, bytes. |
| Use 0 to disable the threshold. |
| @end table |
| |
| @b{Since:} |
| 2.3 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "block-set-write-threshold", |
| "arguments": @{ "node-name": "mydev", |
| "write-threshold": 17179869184 @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} x-blockdev-change |
| |
| Dynamically reconfigure the block driver state graph. It can be used |
| to add, remove, insert or replace a graph node. Currently only the |
| Quorum driver implements this feature to add or remove its child. This |
| is useful to fix a broken quorum child. |
| |
| If @code{node} is specified, it will be inserted under @code{parent}. @code{child} |
| may not be specified in this case. If both @code{parent} and @code{child} are |
| specified but @code{node} is not, @code{child} will be detached from @code{parent}. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{parent: string} |
| the id or name of the parent node. |
| @item @code{child: string} (optional) |
| the name of a child under the given parent node. |
| @item @code{node: string} (optional) |
| the name of the node that will be added. |
| @end table |
| |
| @b{Note:} |
| this command is experimental, and its API is not stable. It |
| does not support all kinds of operations, all kinds of children, nor |
| all block drivers. |
| |
| FIXME Removing children from a quorum node means introducing gaps in the |
| child indices. This cannot be represented in the 'children' list of |
| BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename(). |
| |
| Warning: The data in a new quorum child MUST be consistent with that of |
| the rest of the array. |
| |
| @b{Since:} |
| 2.7 |
| |
| @b{Example:} |
| @example |
| 1. Add a new node to a quorum |
| -> @{ "execute": "blockdev-add", |
| "arguments": @{ |
| "driver": "raw", |
| "node-name": "new_node", |
| "file": @{ "driver": "file", |
| "filename": "test.raw" @} @} @} |
| <- @{ "return": @{@} @} |
| -> @{ "execute": "x-blockdev-change", |
| "arguments": @{ "parent": "disk1", |
| "node": "new_node" @} @} |
| <- @{ "return": @{@} @} |
| |
| 2. Delete a quorum's node |
| -> @{ "execute": "x-blockdev-change", |
| "arguments": @{ "parent": "disk1", |
| "child": "children.1" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} x-blockdev-set-iothread |
| |
| Move @code{node} and its children into the @code{iothread}. If @code{iothread} is null then |
| move @code{node} and its children into the main loop. |
| |
| The node must not be attached to a BlockBackend. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{node-name: string} |
| the name of the block driver node |
| @item @code{iothread: StrOrNull} |
| the name of the IOThread object or null for the main loop |
| @item @code{force: boolean} (optional) |
| true if the node and its children should be moved when a BlockBackend |
| is already attached |
| @end table |
| |
| @b{Note:} |
| this command is experimental and intended for test cases that need |
| control over IOThreads only. |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| 1. Move a node into an IOThread |
| -> @{ "execute": "x-blockdev-set-iothread", |
| "arguments": @{ "node-name": "disk1", |
| "iothread": "iothread0" @} @} |
| <- @{ "return": @{@} @} |
| |
| 2. Move a node into the main loop |
| -> @{ "execute": "x-blockdev-set-iothread", |
| "arguments": @{ "node-name": "disk1", |
| "iothread": null @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @subsection Additional block stuff (VM related) |
| |
| |
| @deftp {Enum} BiosAtaTranslation |
| |
| Policy that BIOS should use to interpret cylinder/head/sector |
| addresses. Note that Bochs BIOS and SeaBIOS will not actually |
| translate logical CHS to physical; instead, they will use logical |
| block addressing. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{auto} |
| If cylinder/heads/sizes are passed, choose between none and LBA |
| depending on the size of the disk. If they are not passed, |
| choose none if QEMU can guess that the disk had 16 or fewer |
| heads, large if QEMU can guess that the disk had 131072 or |
| fewer tracks across all heads (i.e. cylinders*heads<131072), |
| otherwise LBA. |
| @item @code{none} |
| The physical disk geometry is equal to the logical geometry. |
| @item @code{lba} |
| Assume 63 sectors per track and one of 16, 32, 64, 128 or 255 |
| heads (if fewer than 255 are enough to cover the whole disk |
| with 1024 cylinders/head). The number of cylinders/head is |
| then computed based on the number of sectors and heads. |
| @item @code{large} |
| The number of cylinders per head is scaled down to 1024 |
| by correspondingly scaling up the number of heads. |
| @item @code{rechs} |
| Same as @code{large}, but first convert a 16-head geometry to |
| 15-head, by proportionally scaling up the number of |
| cylinders/head. |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} FloppyDriveType |
| |
| Type of Floppy drive to be emulated by the Floppy Disk Controller. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{144} |
| 1.44MB 3.5" drive |
| @item @code{288} |
| 2.88MB 3.5" drive |
| @item @code{120} |
| 1.2MB 5.25" drive |
| @item @code{none} |
| No drive connected |
| @item @code{auto} |
| Automatically determined by inserted media at boot |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} BlockdevSnapshotInternal |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{device: string} |
| the device name or node-name of a root node to generate the snapshot |
| from |
| @item @code{name: string} |
| the name of the internal snapshot to be created |
| @end table |
| |
| @b{Notes:} |
| In transaction, if @code{name} is empty, or any snapshot matching @code{name} |
| exists, the operation will fail. Only some image formats support it, |
| for example, qcow2, rbd, and sheepdog. |
| |
| @b{Since:} |
| 1.7 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} blockdev-snapshot-internal-sync |
| |
| Synchronously take an internal snapshot of a block device, when the |
| format of the image used supports it. If the name is an empty |
| string, or a snapshot with name already exists, the operation will |
| fail. |
| |
| For the arguments, see the documentation of BlockdevSnapshotInternal. |
| |
| @b{Returns:} |
| nothing on success |
| |
| If @code{device} is not a valid block device, GenericError |
| |
| If any snapshot matching @code{name} exists, or @code{name} is empty, |
| GenericError |
| |
| If the format of the image used does not support it, |
| BlockFormatFeatureNotSupported |
| |
| @b{Since:} |
| 1.7 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-snapshot-internal-sync", |
| "arguments": @{ "device": "ide-hd0", |
| "name": "snapshot0" @} |
| @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} blockdev-snapshot-delete-internal-sync |
| |
| Synchronously delete an internal snapshot of a block device, when the format |
| of the image used support it. The snapshot is identified by name or id or |
| both. One of the name or id is required. Return SnapshotInfo for the |
| successfully deleted snapshot. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| the device name or node-name of a root node to delete the snapshot |
| from |
| @item @code{id: string} (optional) |
| optional the snapshot's ID to be deleted |
| @item @code{name: string} (optional) |
| optional the snapshot's name to be deleted |
| @end table |
| |
| @b{Returns:} |
| SnapshotInfo on success |
| If @code{device} is not a valid block device, GenericError |
| If snapshot not found, GenericError |
| If the format of the image used does not support it, |
| BlockFormatFeatureNotSupported |
| If @code{id} and @code{name} are both not specified, GenericError |
| |
| @b{Since:} |
| 1.7 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "blockdev-snapshot-delete-internal-sync", |
| "arguments": @{ "device": "ide-hd0", |
| "name": "snapshot0" @} |
| @} |
| <- @{ "return": @{ |
| "id": "1", |
| "name": "snapshot0", |
| "vm-state-size": 0, |
| "date-sec": 1000012, |
| "date-nsec": 10, |
| "vm-clock-sec": 100, |
| "vm-clock-nsec": 20 |
| @} |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} eject |
| |
| Ejects a device from a removable drive. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} (optional) |
| Block device name (deprecated, use @code{id} instead) |
| @item @code{id: string} (optional) |
| The name or QOM path of the guest device (since: 2.8) |
| @item @code{force: boolean} (optional) |
| If true, eject regardless of whether the drive is locked. |
| If not specified, the default value is false. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| If @code{device} is not a valid block device, DeviceNotFound |
| |
| @b{Notes:} |
| Ejecting a device with no media results in success |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "eject", "arguments": @{ "id": "ide1-0-1" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} nbd-server-start |
| |
| Start an NBD server listening on the given host and port. Block |
| devices can then be exported using @code{nbd-server-add}. The NBD |
| server will present them as named exports; for example, another |
| QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME". |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{addr: SocketAddressLegacy} |
| Address on which to listen. |
| @item @code{tls-creds: string} (optional) |
| (optional) ID of the TLS credentials object. Since 2.6 |
| @end table |
| |
| @b{Returns:} |
| error if the server is already running. |
| |
| @b{Since:} |
| 1.3.0 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} nbd-server-add |
| |
| Export a block node to QEMU's embedded NBD server. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| The device name or node name of the node to be exported |
| @item @code{name: string} (optional) |
| Export name. If unspecified, the @code{device} parameter is used as the |
| export name. (Since 2.12) |
| @item @code{writable: boolean} (optional) |
| Whether clients should be able to write to the device via the |
| NBD connection (default false). |
| @end table |
| |
| @b{Returns:} |
| error if the server is not running, or export with the same name |
| already exists. |
| |
| @b{Since:} |
| 1.3.0 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} NbdServerRemoveMode |
| |
| Mode for removing an NBD export. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{safe} |
| Remove export if there are no existing connections, fail otherwise. |
| @item @code{hard} |
| Drop all connections immediately and remove export. |
| @end table |
| Potential additional modes to be added in the future: |
| |
| hide: Just hide export from new clients, leave existing connections as is. |
| Remove export after all clients are disconnected. |
| |
| soft: Hide export from new clients, answer with ESHUTDOWN for all further |
| requests from existing clients. |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} nbd-server-remove |
| |
| Remove NBD export by name. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{name: string} |
| Export name. |
| @item @code{mode: NbdServerRemoveMode} (optional) |
| Mode of command operation. See @code{NbdServerRemoveMode} description. |
| Default is 'safe'. |
| @end table |
| |
| @b{Returns:} |
| error if |
| @itemize @minus |
| @item |
| the server is not running |
| @item |
| export is not found |
| @item |
| mode is 'safe' and there are existing connections |
| @end itemize |
| |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} nbd-server-stop |
| |
| Stop QEMU's embedded NBD server, and unregister all devices previously |
| added via @code{nbd-server-add}. |
| |
| @b{Since:} |
| 1.3.0 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} DEVICE_TRAY_MOVED |
| |
| Emitted whenever the tray of a removable device is moved by the guest or by |
| HMP/QMP commands |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| Block device name. This is always present for compatibility |
| reasons, but it can be empty ("") if the image does not |
| have a device name associated. |
| @item @code{id: string} |
| The name or QOM path of the guest device (since 2.8) |
| @item @code{tray-open: boolean} |
| true if the tray has been opened or false if it has been closed |
| @end table |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "DEVICE_TRAY_MOVED", |
| "data": @{ "device": "ide1-cd0", |
| "id": "/machine/unattached/device[22]", |
| "tray-open": true |
| @}, |
| "timestamp": @{ "seconds": 1265044230, "microseconds": 450486 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} QuorumOpType |
| |
| An enumeration of the quorum operation types |
| |
| @b{Values:} |
| @table @asis |
| @item @code{read} |
| read operation |
| @item @code{write} |
| write operation |
| @item @code{flush} |
| flush operation |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Event {} QUORUM_FAILURE |
| |
| Emitted by the Quorum block driver if it fails to establish a quorum |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{reference: string} |
| device name if defined else node name |
| @item @code{sector-num: int} |
| number of the first sector of the failed read operation |
| @item @code{sectors-count: int} |
| failed read operation sector count |
| @end table |
| |
| @b{Note:} |
| This event is rate-limited. |
| |
| @b{Since:} |
| 2.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "QUORUM_FAILURE", |
| "data": @{ "reference": "usr1", "sector-num": 345435, "sectors-count": 5 @}, |
| "timestamp": @{ "seconds": 1344522075, "microseconds": 745528 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} QUORUM_REPORT_BAD |
| |
| Emitted to report a corruption of a Quorum file |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{type: QuorumOpType} |
| quorum operation type (Since 2.6) |
| @item @code{error: string} (optional) |
| error message. Only present on failure. This field |
| contains a human-readable error message. There are no semantics other |
| than that the block layer reported an error and clients should not |
| try to interpret the error string. |
| @item @code{node-name: string} |
| the graph node name of the block driver state |
| @item @code{sector-num: int} |
| number of the first sector of the failed read operation |
| @item @code{sectors-count: int} |
| failed read operation sector count |
| @end table |
| |
| @b{Note:} |
| This event is rate-limited. |
| |
| @b{Since:} |
| 2.0 |
| |
| @b{Example:} |
| @example |
| 1. Read operation |
| |
| @{ "event": "QUORUM_REPORT_BAD", |
| "data": @{ "node-name": "node0", "sector-num": 345435, "sectors-count": 5, |
| "type": "read" @}, |
| "timestamp": @{ "seconds": 1344522075, "microseconds": 745528 @} @} |
| |
| 2. Flush operation |
| |
| @{ "event": "QUORUM_REPORT_BAD", |
| "data": @{ "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, |
| "type": "flush", "error": "Broken pipe" @}, |
| "timestamp": @{ "seconds": 1456406829, "microseconds": 291763 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @section Character devices |
| |
| |
| @deftp {Object} ChardevInfo |
| |
| Information about a character device. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{label: string} |
| the label of the character device |
| @item @code{filename: string} |
| the filename of the character device |
| @item @code{frontend-open: boolean} |
| shows whether the frontend device attached to this backend |
| (eg. with the chardev=... option) is in open or closed state |
| (since 2.1) |
| @end table |
| |
| @b{Notes:} |
| @code{filename} is encoded using the QEMU command line character device |
| encoding. See the QEMU man page for details. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-chardev |
| |
| Returns information about current character devices. |
| |
| @b{Returns:} |
| a list of @code{ChardevInfo} |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-chardev" @} |
| <- @{ |
| "return": [ |
| @{ |
| "label": "charchannel0", |
| "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server", |
| "frontend-open": false |
| @}, |
| @{ |
| "label": "charmonitor", |
| "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server", |
| "frontend-open": true |
| @}, |
| @{ |
| "label": "charserial0", |
| "filename": "pty:/dev/pts/2", |
| "frontend-open": true |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} ChardevBackendInfo |
| |
| Information about a character device backend |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| The backend name |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-chardev-backends |
| |
| Returns information about character device backends. |
| |
| @b{Returns:} |
| a list of @code{ChardevBackendInfo} |
| |
| @b{Since:} |
| 2.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-chardev-backends" @} |
| <- @{ |
| "return":[ |
| @{ |
| "name":"udp" |
| @}, |
| @{ |
| "name":"tcp" |
| @}, |
| @{ |
| "name":"unix" |
| @}, |
| @{ |
| "name":"spiceport" |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} DataFormat |
| |
| An enumeration of data format. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{utf8} |
| Data is a UTF-8 string (RFC 3629) |
| @item @code{base64} |
| Data is Base64 encoded binary (RFC 3548) |
| @end table |
| |
| @b{Since:} |
| 1.4 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} ringbuf-write |
| |
| Write to a ring buffer character device. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| the ring buffer character device name |
| @item @code{data: string} |
| data to write |
| @item @code{format: DataFormat} (optional) |
| data encoding (default 'utf8'). |
| @itemize @minus |
| @item |
| base64: data must be base64 encoded text. Its binary |
| decoding gets written. |
| @item |
| utf8: data's UTF-8 encoding is written |
| @item |
| data itself is always Unicode regardless of format, like |
| any other string. |
| @end itemize |
| |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 1.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "ringbuf-write", |
| "arguments": @{ "device": "foo", |
| "data": "abcdefgh", |
| "format": "utf8" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} ringbuf-read |
| |
| Read from a ring buffer character device. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| the ring buffer character device name |
| @item @code{size: int} |
| how many bytes to read at most |
| @item @code{format: DataFormat} (optional) |
| data encoding (default 'utf8'). |
| @itemize @minus |
| @item |
| base64: the data read is returned in base64 encoding. |
| @item |
| utf8: the data read is interpreted as UTF-8. |
| Bug: can screw up when the buffer contains invalid UTF-8 |
| sequences, NUL characters, after the ring buffer lost |
| data, and when reading stops because the size limit is |
| reached. |
| @item |
| The return value is always Unicode regardless of format, |
| like any other string. |
| @end itemize |
| |
| @end table |
| |
| @b{Returns:} |
| data read from the device |
| |
| @b{Since:} |
| 1.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "ringbuf-read", |
| "arguments": @{ "device": "foo", |
| "size": 1000, |
| "format": "utf8" @} @} |
| <- @{ "return": "abcdefgh" @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} ChardevCommon |
| |
| Configuration shared across all chardev backends |
| |
| @b{Members:} |
| @table @asis |
| @item @code{logfile: string} (optional) |
| The name of a logfile to save output |
| @item @code{logappend: boolean} (optional) |
| true to append instead of truncate |
| (default to false to truncate) |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevFile |
| |
| Configuration info for file chardevs. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{in: string} (optional) |
| The name of the input file |
| @item @code{out: string} |
| The name of the output file |
| @item @code{append: boolean} (optional) |
| Open the file in append mode (default false to |
| truncate) (Since 2.6) |
| @item The members of @code{ChardevCommon} |
| @end table |
| |
| @b{Since:} |
| 1.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevHostdev |
| |
| Configuration info for device and pipe chardevs. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{device: string} |
| The name of the special file for the device, |
| i.e. /dev/ttyS0 on Unix or COM1: on Windows |
| @item The members of @code{ChardevCommon} |
| @end table |
| |
| @b{Since:} |
| 1.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevSocket |
| |
| Configuration info for (stream) socket chardevs. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{addr: SocketAddressLegacy} |
| socket address to listen on (server=true) |
| or connect to (server=false) |
| @item @code{tls-creds: string} (optional) |
| the ID of the TLS credentials object (since 2.6) |
| @item @code{server: boolean} (optional) |
| create server socket (default: true) |
| @item @code{wait: boolean} (optional) |
| wait for incoming connection on server |
| sockets (default: false). |
| @item @code{nodelay: boolean} (optional) |
| set TCP_NODELAY socket option (default: false) |
| @item @code{telnet: boolean} (optional) |
| enable telnet protocol on server |
| sockets (default: false) |
| @item @code{tn3270: boolean} (optional) |
| enable tn3270 protocol on server |
| sockets (default: false) (Since: 2.10) |
| @item @code{reconnect: int} (optional) |
| For a client socket, if a socket is disconnected, |
| then attempt a reconnect after the given number of seconds. |
| Setting this to zero disables this function. (default: 0) |
| (Since: 2.2) |
| @item The members of @code{ChardevCommon} |
| @end table |
| |
| @b{Since:} |
| 1.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevUdp |
| |
| Configuration info for datagram socket chardevs. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{remote: SocketAddressLegacy} |
| remote address |
| @item @code{local: SocketAddressLegacy} (optional) |
| local address |
| @item The members of @code{ChardevCommon} |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevMux |
| |
| Configuration info for mux chardevs. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{chardev: string} |
| name of the base chardev. |
| @item The members of @code{ChardevCommon} |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevStdio |
| |
| Configuration info for stdio chardevs. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{signal: boolean} (optional) |
| Allow signals (such as SIGINT triggered by ^C) |
| be delivered to qemu. Default: true in -nographic mode, |
| false otherwise. |
| @item The members of @code{ChardevCommon} |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevSpiceChannel |
| |
| Configuration info for spice vm channel chardevs. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: string} |
| kind of channel (for example vdagent). |
| @item The members of @code{ChardevCommon} |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevSpicePort |
| |
| Configuration info for spice port chardevs. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{fqdn: string} |
| name of the channel (see docs/spice-port-fqdn.txt) |
| @item The members of @code{ChardevCommon} |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevVC |
| |
| Configuration info for virtual console chardevs. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{width: int} (optional) |
| console width, in pixels |
| @item @code{height: int} (optional) |
| console height, in pixels |
| @item @code{cols: int} (optional) |
| console width, in chars |
| @item @code{rows: int} (optional) |
| console height, in chars |
| @item The members of @code{ChardevCommon} |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevRingbuf |
| |
| Configuration info for ring buffer chardevs. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{size: int} (optional) |
| ring buffer size, must be power of two, default is 65536 |
| @item The members of @code{ChardevCommon} |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevBackend |
| |
| Configuration info for the new chardev backend. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type} |
| One of @t{"file"}, @t{"serial"}, @t{"parallel"}, @t{"pipe"}, @t{"socket"}, @t{"udp"}, @t{"pty"}, @t{"null"}, @t{"mux"}, @t{"msmouse"}, @t{"wctablet"}, @t{"braille"}, @t{"testdev"}, @t{"stdio"}, @t{"console"}, @t{"spicevmc"}, @t{"spiceport"}, @t{"vc"}, @t{"ringbuf"}, @t{"memory"} |
| @item @code{data: ChardevFile} when @code{type} is @t{"file"} |
| @item @code{data: ChardevHostdev} when @code{type} is @t{"serial"} |
| @item @code{data: ChardevHostdev} when @code{type} is @t{"parallel"} |
| @item @code{data: ChardevHostdev} when @code{type} is @t{"pipe"} |
| @item @code{data: ChardevSocket} when @code{type} is @t{"socket"} |
| @item @code{data: ChardevUdp} when @code{type} is @t{"udp"} |
| @item @code{data: ChardevCommon} when @code{type} is @t{"pty"} |
| @item @code{data: ChardevCommon} when @code{type} is @t{"null"} |
| @item @code{data: ChardevMux} when @code{type} is @t{"mux"} |
| @item @code{data: ChardevCommon} when @code{type} is @t{"msmouse"} |
| @item @code{data: ChardevCommon} when @code{type} is @t{"wctablet"} |
| @item @code{data: ChardevCommon} when @code{type} is @t{"braille"} |
| @item @code{data: ChardevCommon} when @code{type} is @t{"testdev"} |
| @item @code{data: ChardevStdio} when @code{type} is @t{"stdio"} |
| @item @code{data: ChardevCommon} when @code{type} is @t{"console"} |
| @item @code{data: ChardevSpiceChannel} when @code{type} is @t{"spicevmc"} |
| @item @code{data: ChardevSpicePort} when @code{type} is @t{"spiceport"} |
| @item @code{data: ChardevVC} when @code{type} is @t{"vc"} |
| @item @code{data: ChardevRingbuf} when @code{type} is @t{"ringbuf"} |
| @item @code{data: ChardevRingbuf} when @code{type} is @t{"memory"} |
| @end table |
| |
| @b{Since:} |
| 1.4 (testdev since 2.2, wctablet since 2.9) |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ChardevReturn |
| |
| Return info about the chardev backend just created. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{pty: string} (optional) |
| name of the slave pseudoterminal device, present if |
| and only if a chardev of type 'pty' was created |
| @end table |
| |
| @b{Since:} |
| 1.4 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} chardev-add |
| |
| Add a character device backend |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| the chardev's ID, must be unique |
| @item @code{backend: ChardevBackend} |
| backend type and parameters |
| @end table |
| |
| @b{Returns:} |
| ChardevReturn. |
| |
| @b{Since:} |
| 1.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute" : "chardev-add", |
| "arguments" : @{ "id" : "foo", |
| "backend" : @{ "type" : "null", "data" : @{@} @} @} @} |
| <- @{ "return": @{@} @} |
| |
| -> @{ "execute" : "chardev-add", |
| "arguments" : @{ "id" : "bar", |
| "backend" : @{ "type" : "file", |
| "data" : @{ "out" : "/tmp/bar.log" @} @} @} @} |
| <- @{ "return": @{@} @} |
| |
| -> @{ "execute" : "chardev-add", |
| "arguments" : @{ "id" : "baz", |
| "backend" : @{ "type" : "pty", "data" : @{@} @} @} @} |
| <- @{ "return": @{ "pty" : "/dev/pty/42" @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} chardev-change |
| |
| Change a character device backend |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| the chardev's ID, must exist |
| @item @code{backend: ChardevBackend} |
| new backend type and parameters |
| @end table |
| |
| @b{Returns:} |
| ChardevReturn. |
| |
| @b{Since:} |
| 2.10 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute" : "chardev-change", |
| "arguments" : @{ "id" : "baz", |
| "backend" : @{ "type" : "pty", "data" : @{@} @} @} @} |
| <- @{ "return": @{ "pty" : "/dev/pty/42" @} @} |
| |
| -> @{"execute" : "chardev-change", |
| "arguments" : @{ |
| "id" : "charchannel2", |
| "backend" : @{ |
| "type" : "socket", |
| "data" : @{ |
| "addr" : @{ |
| "type" : "unix" , |
| "data" : @{ |
| "path" : "/tmp/charchannel2.socket" |
| @} |
| @}, |
| "server" : true, |
| "wait" : false @}@}@}@} |
| <- @{"return": @{@}@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} chardev-remove |
| |
| Remove a character device backend |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| the chardev's ID, must exist and not be in use |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 1.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "chardev-remove", "arguments": @{ "id" : "foo" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} chardev-send-break |
| |
| Send a break to a character device |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| the chardev's ID, must exist |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 2.10 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "chardev-send-break", "arguments": @{ "id" : "foo" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} VSERPORT_CHANGE |
| |
| Emitted when the guest opens or closes a virtio-serial port. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| device identifier of the virtio-serial port |
| @item @code{open: boolean} |
| true if the guest has opened the virtio-serial port |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "VSERPORT_CHANGE", |
| "data": @{ "id": "channel0", "open": true @}, |
| "timestamp": @{ "seconds": 1401385907, "microseconds": 422329 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @section Net devices |
| |
| |
| @deftypefn Command {} set_link |
| |
| Sets the link status of a virtual network adapter. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{name: string} |
| the device name of the virtual network adapter |
| @item @code{up: boolean} |
| true to set the link status to be up |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If @code{name} is not a valid network device, DeviceNotFound |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| Not all network adapters support setting link status. This command |
| will succeed even if the network adapter does not support link status |
| notification. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "set_link", |
| "arguments": @{ "name": "e1000.0", "up": false @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} netdev_add |
| |
| Add a network backend. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{type: string} |
| the type of network backend. Possible values are listed in |
| NetClientDriver (excluding 'none' and 'nic') |
| @item @code{id: string} |
| the name of the new network backend |
| @end table |
| Additional arguments depend on the type. |
| |
| @b{TODO:} |
| This command effectively bypasses QAPI completely due to its |
| "additional arguments" business. It shouldn't have been added to |
| the schema in this form. It should be qapified properly, or |
| replaced by a properly qapified command. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Returns:} |
| Nothing on success |
| If @code{type} is not a valid network backend, DeviceNotFound |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "netdev_add", |
| "arguments": @{ "type": "user", "id": "netdev1", |
| "dnssearch": "example.org" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} netdev_del |
| |
| Remove a network backend. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| the name of the network backend to remove |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If @code{id} is not a valid network backend, DeviceNotFound |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "netdev_del", "arguments": @{ "id": "netdev1" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} NetdevNoneOptions |
| |
| Use it alone to have zero network devices. |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetLegacyNicOptions |
| |
| Create a new Network Interface Card. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{netdev: string} (optional) |
| id of -netdev to connect to |
| @item @code{macaddr: string} (optional) |
| MAC address |
| @item @code{model: string} (optional) |
| device model (e1000, rtl8139, virtio etc.) |
| @item @code{addr: string} (optional) |
| PCI device address |
| @item @code{vectors: int} (optional) |
| number of MSI-x vectors, 0 to disable MSI-X |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetdevUserOptions |
| |
| Use the user mode network stack which requires no administrator privilege to |
| run. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{hostname: string} (optional) |
| client hostname reported by the builtin DHCP server |
| @item @code{restrict: boolean} (optional) |
| isolate the guest from the host |
| @item @code{ipv4: boolean} (optional) |
| whether to support IPv4, default true for enabled |
| (since 2.6) |
| @item @code{ipv6: boolean} (optional) |
| whether to support IPv6, default true for enabled |
| (since 2.6) |
| @item @code{ip: string} (optional) |
| legacy parameter, use net= instead |
| @item @code{net: string} (optional) |
| IP network address that the guest will see, in the |
| form addr[/netmask] The netmask is optional, and can be |
| either in the form a.b.c.d or as a number of valid top-most |
| bits. Default is 10.0.2.0/24. |
| @item @code{host: string} (optional) |
| guest-visible address of the host |
| @item @code{tftp: string} (optional) |
| root directory of the built-in TFTP server |
| @item @code{bootfile: string} (optional) |
| BOOTP filename, for use with tftp= |
| @item @code{dhcpstart: string} (optional) |
| the first of the 16 IPs the built-in DHCP server can |
| assign |
| @item @code{dns: string} (optional) |
| guest-visible address of the virtual nameserver |
| @item @code{dnssearch: array of String} (optional) |
| list of DNS suffixes to search, passed as DHCP option |
| to the guest |
| @item @code{ipv6-prefix: string} (optional) |
| IPv6 network prefix (default is fec0::) (since |
| 2.6). The network prefix is given in the usual |
| hexadecimal IPv6 address notation. |
| @item @code{ipv6-prefixlen: int} (optional) |
| IPv6 network prefix length (default is 64) |
| (since 2.6) |
| @item @code{ipv6-host: string} (optional) |
| guest-visible IPv6 address of the host (since 2.6) |
| @item @code{ipv6-dns: string} (optional) |
| guest-visible IPv6 address of the virtual |
| nameserver (since 2.6) |
| @item @code{smb: string} (optional) |
| root directory of the built-in SMB server |
| @item @code{smbserver: string} (optional) |
| IP address of the built-in SMB server |
| @item @code{hostfwd: array of String} (optional) |
| redirect incoming TCP or UDP host connections to guest |
| endpoints |
| @item @code{guestfwd: array of String} (optional) |
| forward guest TCP connections |
| @item @code{ipv6-hostfwd: array of String} (optional) |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetdevTapOptions |
| |
| Connect the host TAP network interface name to the VLAN. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{ifname: string} (optional) |
| interface name |
| @item @code{fd: string} (optional) |
| file descriptor of an already opened tap |
| @item @code{fds: string} (optional) |
| multiple file descriptors of already opened multiqueue capable |
| tap |
| @item @code{script: string} (optional) |
| script to initialize the interface |
| @item @code{downscript: string} (optional) |
| script to shut down the interface |
| @item @code{br: string} (optional) |
| bridge name (since 2.8) |
| @item @code{helper: string} (optional) |
| command to execute to configure bridge |
| @item @code{sndbuf: int} (optional) |
| send buffer limit. Understands [TGMKkb] suffixes. |
| @item @code{vnet_hdr: boolean} (optional) |
| enable the IFF_VNET_HDR flag on the tap interface |
| @item @code{vhost: boolean} (optional) |
| enable vhost-net network accelerator |
| @item @code{vhostfd: string} (optional) |
| file descriptor of an already opened vhost net device |
| @item @code{vhostfds: string} (optional) |
| file descriptors of multiple already opened vhost net |
| devices |
| @item @code{vhostforce: boolean} (optional) |
| vhost on for non-MSIX virtio guests |
| @item @code{queues: int} (optional) |
| number of queues to be created for multiqueue capable tap |
| @item @code{poll-us: int} (optional) |
| maximum number of microseconds that could |
| be spent on busy polling for tap (since 2.7) |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetdevSocketOptions |
| |
| Connect the VLAN to a remote VLAN in another QEMU virtual machine using a TCP |
| socket connection. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{fd: string} (optional) |
| file descriptor of an already opened socket |
| @item @code{listen: string} (optional) |
| port number, and optional hostname, to listen on |
| @item @code{connect: string} (optional) |
| port number, and optional hostname, to connect to |
| @item @code{mcast: string} (optional) |
| UDP multicast address and port number |
| @item @code{localaddr: string} (optional) |
| source address and port for multicast and udp packets |
| @item @code{udp: string} (optional) |
| UDP unicast address and port number |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetdevL2TPv3Options |
| |
| Connect the VLAN to Ethernet over L2TPv3 Static tunnel |
| |
| @b{Members:} |
| @table @asis |
| @item @code{src: string} |
| source address |
| @item @code{dst: string} |
| destination address |
| @item @code{srcport: string} (optional) |
| source port - mandatory for udp, optional for ip |
| @item @code{dstport: string} (optional) |
| destination port - mandatory for udp, optional for ip |
| @item @code{ipv6: boolean} (optional) |
| force the use of ipv6 |
| @item @code{udp: boolean} (optional) |
| use the udp version of l2tpv3 encapsulation |
| @item @code{cookie64: boolean} (optional) |
| use 64 bit coookies |
| @item @code{counter: boolean} (optional) |
| have sequence counter |
| @item @code{pincounter: boolean} (optional) |
| pin sequence counter to zero - |
| workaround for buggy implementations or |
| networks with packet reorder |
| @item @code{txcookie: int} (optional) |
| 32 or 64 bit transmit cookie |
| @item @code{rxcookie: int} (optional) |
| 32 or 64 bit receive cookie |
| @item @code{txsession: int} |
| 32 bit transmit session |
| @item @code{rxsession: int} (optional) |
| 32 bit receive session - if not specified |
| set to the same value as transmit |
| @item @code{offset: int} (optional) |
| additional offset - allows the insertion of |
| additional application-specific data before the packet payload |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetdevVdeOptions |
| |
| Connect the VLAN to a vde switch running on the host. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{sock: string} (optional) |
| socket path |
| @item @code{port: int} (optional) |
| port number |
| @item @code{group: string} (optional) |
| group owner of socket |
| @item @code{mode: int} (optional) |
| permissions for socket |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetdevBridgeOptions |
| |
| Connect a host TAP network interface to a host bridge device. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{br: string} (optional) |
| bridge name |
| @item @code{helper: string} (optional) |
| command to execute to configure bridge |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetdevHubPortOptions |
| |
| Connect two or more net clients through a software hub. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{hubid: int} |
| hub identifier number |
| @item @code{netdev: string} (optional) |
| used to connect hub to a netdev instead of a device (since 2.12) |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetdevNetmapOptions |
| |
| Connect a client to a netmap-enabled NIC or to a VALE switch port |
| |
| @b{Members:} |
| @table @asis |
| @item @code{ifname: string} |
| Either the name of an existing network interface supported by |
| netmap, or the name of a VALE port (created on the fly). |
| A VALE port name is in the form 'valeXXX:YYY', where XXX and |
| YYY are non-negative integers. XXX identifies a switch and |
| YYY identifies a port of the switch. VALE ports having the |
| same XXX are therefore connected to the same switch. |
| @item @code{devname: string} (optional) |
| path of the netmap device (default: '/dev/netmap'). |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetdevVhostUserOptions |
| |
| Vhost-user network backend |
| |
| @b{Members:} |
| @table @asis |
| @item @code{chardev: string} |
| name of a unix socket chardev |
| @item @code{vhostforce: boolean} (optional) |
| vhost on for non-MSIX virtio guests (default: false). |
| @item @code{queues: int} (optional) |
| number of queues to be created for multiqueue vhost-user |
| (default: 1) (Since 2.5) |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} NetClientDriver |
| |
| Available netdev drivers. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{none} |
| Not documented |
| @item @code{nic} |
| Not documented |
| @item @code{user} |
| Not documented |
| @item @code{tap} |
| Not documented |
| @item @code{l2tpv3} |
| Not documented |
| @item @code{socket} |
| Not documented |
| @item @code{vde} |
| Not documented |
| @item @code{bridge} |
| Not documented |
| @item @code{hubport} |
| Not documented |
| @item @code{netmap} |
| Not documented |
| @item @code{vhost-user} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.7 |
| |
| 'dump' - removed with 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} Netdev |
| |
| Captures the configuration of a network device. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{id: string} |
| identifier for monitor commands. |
| @item @code{type: NetClientDriver} |
| Specify the driver used for interpreting remaining arguments. |
| @item The members of @code{NetdevNoneOptions} when @code{type} is @t{"none"} |
| @item The members of @code{NetLegacyNicOptions} when @code{type} is @t{"nic"} |
| @item The members of @code{NetdevUserOptions} when @code{type} is @t{"user"} |
| @item The members of @code{NetdevTapOptions} when @code{type} is @t{"tap"} |
| @item The members of @code{NetdevL2TPv3Options} when @code{type} is @t{"l2tpv3"} |
| @item The members of @code{NetdevSocketOptions} when @code{type} is @t{"socket"} |
| @item The members of @code{NetdevVdeOptions} when @code{type} is @t{"vde"} |
| @item The members of @code{NetdevBridgeOptions} when @code{type} is @t{"bridge"} |
| @item The members of @code{NetdevHubPortOptions} when @code{type} is @t{"hubport"} |
| @item The members of @code{NetdevNetmapOptions} when @code{type} is @t{"netmap"} |
| @item The members of @code{NetdevVhostUserOptions} when @code{type} is @t{"vhost-user"} |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| 'l2tpv3' - since 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetLegacy |
| |
| Captures the configuration of a network device; legacy. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{vlan: int} (optional) |
| vlan number |
| @item @code{id: string} (optional) |
| identifier for monitor commands |
| @item @code{name: string} (optional) |
| identifier for monitor commands, ignored if @code{id} is present |
| @item @code{opts: NetLegacyOptions} |
| device type specific properties (legacy) |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} NetLegacyOptionsType |
| |
| |
| |
| @b{Values:} |
| @table @asis |
| @item @code{none} |
| Not documented |
| @item @code{nic} |
| Not documented |
| @item @code{user} |
| Not documented |
| @item @code{tap} |
| Not documented |
| @item @code{l2tpv3} |
| Not documented |
| @item @code{socket} |
| Not documented |
| @item @code{vde} |
| Not documented |
| @item @code{bridge} |
| Not documented |
| @item @code{netmap} |
| Not documented |
| @item @code{vhost-user} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NetLegacyOptions |
| |
| Like Netdev, but for use only by the legacy command line options |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: NetLegacyOptionsType} |
| Not documented |
| @item The members of @code{NetdevNoneOptions} when @code{type} is @t{"none"} |
| @item The members of @code{NetLegacyNicOptions} when @code{type} is @t{"nic"} |
| @item The members of @code{NetdevUserOptions} when @code{type} is @t{"user"} |
| @item The members of @code{NetdevTapOptions} when @code{type} is @t{"tap"} |
| @item The members of @code{NetdevL2TPv3Options} when @code{type} is @t{"l2tpv3"} |
| @item The members of @code{NetdevSocketOptions} when @code{type} is @t{"socket"} |
| @item The members of @code{NetdevVdeOptions} when @code{type} is @t{"vde"} |
| @item The members of @code{NetdevBridgeOptions} when @code{type} is @t{"bridge"} |
| @item The members of @code{NetdevNetmapOptions} when @code{type} is @t{"netmap"} |
| @item The members of @code{NetdevVhostUserOptions} when @code{type} is @t{"vhost-user"} |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} NetFilterDirection |
| |
| Indicates whether a netfilter is attached to a netdev's transmit queue or |
| receive queue or both. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{all} |
| the filter is attached both to the receive and the transmit |
| queue of the netdev (default). |
| @item @code{rx} |
| the filter is attached to the receive queue of the netdev, |
| where it will receive packets sent to the netdev. |
| @item @code{tx} |
| the filter is attached to the transmit queue of the netdev, |
| where it will receive packets sent by the netdev. |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} RxState |
| |
| Packets receiving state |
| |
| @b{Values:} |
| @table @asis |
| @item @code{normal} |
| filter assigned packets according to the mac-table |
| @item @code{none} |
| don't receive any assigned packet |
| @item @code{all} |
| receive all assigned packets |
| @end table |
| |
| @b{Since:} |
| 1.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} RxFilterInfo |
| |
| Rx-filter information for a NIC. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| net client name |
| @item @code{promiscuous: boolean} |
| whether promiscuous mode is enabled |
| @item @code{multicast: RxState} |
| multicast receive state |
| @item @code{unicast: RxState} |
| unicast receive state |
| @item @code{vlan: RxState} |
| vlan receive state (Since 2.0) |
| @item @code{broadcast-allowed: boolean} |
| whether to receive broadcast |
| @item @code{multicast-overflow: boolean} |
| multicast table is overflowed or not |
| @item @code{unicast-overflow: boolean} |
| unicast table is overflowed or not |
| @item @code{main-mac: string} |
| the main macaddr string |
| @item @code{vlan-table: array of int} |
| a list of active vlan id |
| @item @code{unicast-table: array of string} |
| a list of unicast macaddr string |
| @item @code{multicast-table: array of string} |
| a list of multicast macaddr string |
| @end table |
| |
| @b{Since:} |
| 1.6 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-rx-filter |
| |
| Return rx-filter information for all NICs (or for the given NIC). |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{name: string} (optional) |
| net client name |
| @end table |
| |
| @b{Returns:} |
| list of @code{RxFilterInfo} for all NICs (or for the given NIC). |
| Returns an error if the given @code{name} doesn't exist, or given |
| NIC doesn't support rx-filter querying, or given net client |
| isn't a NIC. |
| |
| @b{Since:} |
| 1.6 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-rx-filter", "arguments": @{ "name": "vnet0" @} @} |
| <- @{ "return": [ |
| @{ |
| "promiscuous": true, |
| "name": "vnet0", |
| "main-mac": "52:54:00:12:34:56", |
| "unicast": "normal", |
| "vlan": "normal", |
| "vlan-table": [ |
| 4, |
| 0 |
| ], |
| "unicast-table": [ |
| ], |
| "multicast": "normal", |
| "multicast-overflow": false, |
| "unicast-overflow": false, |
| "multicast-table": [ |
| "01:00:5e:00:00:01", |
| "33:33:00:00:00:01", |
| "33:33:ff:12:34:56" |
| ], |
| "broadcast-allowed": false |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} NIC_RX_FILTER_CHANGED |
| |
| Emitted once until the 'query-rx-filter' command is executed, the first event |
| will always be emitted |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{name: string} (optional) |
| net client name |
| @item @code{path: string} |
| device path |
| @end table |
| |
| @b{Since:} |
| 1.6 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "NIC_RX_FILTER_CHANGED", |
| "data": @{ "name": "vnet0", |
| "path": "/machine/peripheral/vnet0/virtio-backend" @}, |
| "timestamp": @{ "seconds": 1368697518, "microseconds": 326866 @} @} |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @section Rocker switch device |
| |
| |
| @deftp {Object} RockerSwitch |
| |
| Rocker switch information. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| switch name |
| @item @code{id: int} |
| switch ID |
| @item @code{ports: int} |
| number of front-panel ports |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-rocker |
| |
| Return rocker switch information. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{name: string} |
| Not documented |
| @end table |
| |
| @b{Returns:} |
| @code{Rocker} information |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-rocker", "arguments": @{ "name": "sw1" @} @} |
| <- @{ "return": @{"name": "sw1", "ports": 2, "id": 1327446905938@}@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} RockerPortDuplex |
| |
| An eumeration of port duplex states. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{half} |
| half duplex |
| @item @code{full} |
| full duplex |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} RockerPortAutoneg |
| |
| An eumeration of port autoneg states. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{off} |
| autoneg is off |
| @item @code{on} |
| autoneg is on |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} RockerPort |
| |
| Rocker switch port information. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| port name |
| @item @code{enabled: boolean} |
| port is enabled for I/O |
| @item @code{link-up: boolean} |
| physical link is UP on port |
| @item @code{speed: int} |
| port link speed in Mbps |
| @item @code{duplex: RockerPortDuplex} |
| port link duplex |
| @item @code{autoneg: RockerPortAutoneg} |
| port link autoneg |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-rocker-ports |
| |
| Return rocker switch port information. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{name: string} |
| Not documented |
| @end table |
| |
| @b{Returns:} |
| a list of @code{RockerPort} information |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-rocker-ports", "arguments": @{ "name": "sw1" @} @} |
| <- @{ "return": [ @{"duplex": "full", "enabled": true, "name": "sw1.1", |
| "autoneg": "off", "link-up": true, "speed": 10000@}, |
| @{"duplex": "full", "enabled": true, "name": "sw1.2", |
| "autoneg": "off", "link-up": true, "speed": 10000@} |
| ]@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} RockerOfDpaFlowKey |
| |
| Rocker switch OF-DPA flow key |
| |
| @b{Members:} |
| @table @asis |
| @item @code{priority: int} |
| key priority, 0 being lowest priority |
| @item @code{tbl-id: int} |
| flow table ID |
| @item @code{in-pport: int} (optional) |
| physical input port |
| @item @code{tunnel-id: int} (optional) |
| tunnel ID |
| @item @code{vlan-id: int} (optional) |
| VLAN ID |
| @item @code{eth-type: int} (optional) |
| Ethernet header type |
| @item @code{eth-src: string} (optional) |
| Ethernet header source MAC address |
| @item @code{eth-dst: string} (optional) |
| Ethernet header destination MAC address |
| @item @code{ip-proto: int} (optional) |
| IP Header protocol field |
| @item @code{ip-tos: int} (optional) |
| IP header TOS field |
| @item @code{ip-dst: string} (optional) |
| IP header destination address |
| @end table |
| |
| @b{Note:} |
| optional members may or may not appear in the flow key |
| depending if they're relevant to the flow key. |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} RockerOfDpaFlowMask |
| |
| Rocker switch OF-DPA flow mask |
| |
| @b{Members:} |
| @table @asis |
| @item @code{in-pport: int} (optional) |
| physical input port |
| @item @code{tunnel-id: int} (optional) |
| tunnel ID |
| @item @code{vlan-id: int} (optional) |
| VLAN ID |
| @item @code{eth-src: string} (optional) |
| Ethernet header source MAC address |
| @item @code{eth-dst: string} (optional) |
| Ethernet header destination MAC address |
| @item @code{ip-proto: int} (optional) |
| IP Header protocol field |
| @item @code{ip-tos: int} (optional) |
| IP header TOS field |
| @end table |
| |
| @b{Note:} |
| optional members may or may not appear in the flow mask |
| depending if they're relevant to the flow mask. |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} RockerOfDpaFlowAction |
| |
| Rocker switch OF-DPA flow action |
| |
| @b{Members:} |
| @table @asis |
| @item @code{goto-tbl: int} (optional) |
| next table ID |
| @item @code{group-id: int} (optional) |
| group ID |
| @item @code{tunnel-lport: int} (optional) |
| tunnel logical port ID |
| @item @code{vlan-id: int} (optional) |
| VLAN ID |
| @item @code{new-vlan-id: int} (optional) |
| new VLAN ID |
| @item @code{out-pport: int} (optional) |
| physical output port |
| @end table |
| |
| @b{Note:} |
| optional members may or may not appear in the flow action |
| depending if they're relevant to the flow action. |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} RockerOfDpaFlow |
| |
| Rocker switch OF-DPA flow |
| |
| @b{Members:} |
| @table @asis |
| @item @code{cookie: int} |
| flow unique cookie ID |
| @item @code{hits: int} |
| count of matches (hits) on flow |
| @item @code{key: RockerOfDpaFlowKey} |
| flow key |
| @item @code{mask: RockerOfDpaFlowMask} |
| flow mask |
| @item @code{action: RockerOfDpaFlowAction} |
| flow action |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-rocker-of-dpa-flows |
| |
| Return rocker OF-DPA flow information. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{name: string} |
| switch name |
| @item @code{tbl-id: int} (optional) |
| flow table ID. If tbl-id is not specified, returns |
| flow information for all tables. |
| @end table |
| |
| @b{Returns:} |
| rocker OF-DPA flow information |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-rocker-of-dpa-flows", |
| "arguments": @{ "name": "sw1" @} @} |
| <- @{ "return": [ @{"key": @{"in-pport": 0, "priority": 1, "tbl-id": 0@}, |
| "hits": 138, |
| "cookie": 0, |
| "action": @{"goto-tbl": 10@}, |
| "mask": @{"in-pport": 4294901760@} |
| @}, |
| @{...more...@}, |
| ]@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} RockerOfDpaGroup |
| |
| Rocker switch OF-DPA group |
| |
| @b{Members:} |
| @table @asis |
| @item @code{id: int} |
| group unique ID |
| @item @code{type: int} |
| group type |
| @item @code{vlan-id: int} (optional) |
| VLAN ID |
| @item @code{pport: int} (optional) |
| physical port number |
| @item @code{index: int} (optional) |
| group index, unique with group type |
| @item @code{out-pport: int} (optional) |
| output physical port number |
| @item @code{group-id: int} (optional) |
| next group ID |
| @item @code{set-vlan-id: int} (optional) |
| VLAN ID to set |
| @item @code{pop-vlan: int} (optional) |
| pop VLAN headr from packet |
| @item @code{group-ids: array of int} (optional) |
| list of next group IDs |
| @item @code{set-eth-src: string} (optional) |
| set source MAC address in Ethernet header |
| @item @code{set-eth-dst: string} (optional) |
| set destination MAC address in Ethernet header |
| @item @code{ttl-check: int} (optional) |
| perform TTL check |
| @end table |
| |
| @b{Note:} |
| optional members may or may not appear in the group depending |
| if they're relevant to the group type. |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-rocker-of-dpa-groups |
| |
| Return rocker OF-DPA group information. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{name: string} |
| switch name |
| @item @code{type: int} (optional) |
| group type. If type is not specified, returns |
| group information for all group types. |
| @end table |
| |
| @b{Returns:} |
| rocker OF-DPA group information |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-rocker-of-dpa-groups", |
| "arguments": @{ "name": "sw1" @} @} |
| <- @{ "return": [ @{"type": 0, "out-pport": 2, |
| "pport": 2, "vlan-id": 3841, |
| "pop-vlan": 1, "id": 251723778@}, |
| @{"type": 0, "out-pport": 0, |
| "pport": 0, "vlan-id": 3841, |
| "pop-vlan": 1, "id": 251723776@}, |
| @{"type": 0, "out-pport": 1, |
| "pport": 1, "vlan-id": 3840, |
| "pop-vlan": 1, "id": 251658241@}, |
| @{"type": 0, "out-pport": 0, |
| "pport": 0, "vlan-id": 3840, |
| "pop-vlan": 1, "id": 251658240@} |
| ]@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @section TPM (trusted platform module) devices |
| |
| |
| @deftp {Enum} TpmModel |
| |
| An enumeration of TPM models |
| |
| @b{Values:} |
| @table @asis |
| @item @code{tpm-tis} |
| TPM TIS model |
| @item @code{tpm-crb} |
| TPM CRB model (since 2.12) |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-tpm-models |
| |
| Return a list of supported TPM models |
| |
| @b{Returns:} |
| a list of TpmModel |
| |
| @b{Since:} |
| 1.5 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-tpm-models" @} |
| <- @{ "return": [ "tpm-tis", "tpm-crb" ] @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} TpmType |
| |
| An enumeration of TPM types |
| |
| @b{Values:} |
| @table @asis |
| @item @code{passthrough} |
| TPM passthrough type |
| @item @code{emulator} |
| Software Emulator TPM type |
| Since: 2.11 |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-tpm-types |
| |
| Return a list of supported TPM types |
| |
| @b{Returns:} |
| a list of TpmType |
| |
| @b{Since:} |
| 1.5 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-tpm-types" @} |
| <- @{ "return": [ "passthrough", "emulator" ] @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} TPMPassthroughOptions |
| |
| Information about the TPM passthrough type |
| |
| @b{Members:} |
| @table @asis |
| @item @code{path: string} (optional) |
| string describing the path used for accessing the TPM device |
| @item @code{cancel-path: string} (optional) |
| string showing the TPM's sysfs cancel file |
| for cancellation of TPM commands while they are executing |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} TPMEmulatorOptions |
| |
| Information about the TPM emulator type |
| |
| @b{Members:} |
| @table @asis |
| @item @code{chardev: string} |
| Name of a unix socket chardev |
| @end table |
| |
| @b{Since:} |
| 2.11 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} TpmTypeOptions |
| |
| A union referencing different TPM backend types' configuration options |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type} |
| 'passthrough' The configuration options for the TPM passthrough type |
| 'emulator' The configuration options for TPM emulator backend type |
| @item @code{data: TPMPassthroughOptions} when @code{type} is @t{"passthrough"} |
| @item @code{data: TPMEmulatorOptions} when @code{type} is @t{"emulator"} |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} TPMInfo |
| |
| Information about the TPM |
| |
| @b{Members:} |
| @table @asis |
| @item @code{id: string} |
| The Id of the TPM |
| @item @code{model: TpmModel} |
| The TPM frontend model |
| @item @code{options: TpmTypeOptions} |
| The TPM (backend) type configuration options |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-tpm |
| |
| Return information about the TPM device |
| |
| @b{Returns:} |
| @code{TPMInfo} on success |
| |
| @b{Since:} |
| 1.5 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-tpm" @} |
| <- @{ "return": |
| [ |
| @{ "model": "tpm-tis", |
| "options": |
| @{ "type": "passthrough", |
| "data": |
| @{ "cancel-path": "/sys/class/misc/tpm0/device/cancel", |
| "path": "/dev/tpm0" |
| @} |
| @}, |
| "id": "tpm0" |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @section Remote desktop |
| |
| |
| @deftypefn Command {} set_password |
| |
| Sets the password of a remote display session. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{protocol: string} |
| `vnc' to modify the VNC server password |
| `spice' to modify the Spice server password |
| @item @code{password: string} |
| the new password |
| @item @code{connected: string} (optional) |
| how to handle existing clients when changing the |
| password. If nothing is specified, defaults to `keep' |
| `fail' to fail the command if clients are connected |
| `disconnect' to disconnect existing clients |
| `keep' to maintain existing clients |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If Spice is not enabled, DeviceNotFound |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "set_password", "arguments": @{ "protocol": "vnc", |
| "password": "secret" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} expire_password |
| |
| Expire the password of a remote display server. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{protocol: string} |
| the name of the remote display protocol `vnc' or `spice' |
| @item @code{time: string} |
| when to expire the password. |
| `now' to expire the password immediately |
| `never' to cancel password expiration |
| `+INT' where INT is the number of seconds from now (integer) |
| `INT' where INT is the absolute time in seconds |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If @code{protocol} is `spice' and Spice is not active, DeviceNotFound |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| Time is relative to the server and currently there is no way to |
| coordinate server time with client time. It is not recommended to |
| use the absolute time version of the @code{time} parameter unless you're |
| sure you are on the same machine as the QEMU instance. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "expire_password", "arguments": @{ "protocol": "vnc", |
| "time": "+60" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} screendump |
| |
| Write a PPM of the VGA screen to a file. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{filename: string} |
| the path of a new PPM file to store the image |
| @item @code{device: string} (optional) |
| ID of the display device that should be dumped. If this parameter |
| is missing, the primary display will be used. (Since 2.12) |
| @item @code{head: int} (optional) |
| head to use in case the device supports multiple heads. If this |
| parameter is missing, head #0 will be used. Also note that the head |
| can only be specified in conjunction with the device ID. (Since 2.12) |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "screendump", |
| "arguments": @{ "filename": "/tmp/image" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @subsection Spice |
| |
| |
| @deftp {Object} SpiceBasicInfo |
| |
| The basic information for SPICE network connection |
| |
| @b{Members:} |
| @table @asis |
| @item @code{host: string} |
| IP address |
| @item @code{port: string} |
| port number |
| @item @code{family: NetworkAddressFamily} |
| address family |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SpiceServerInfo |
| |
| Information about a SPICE server |
| |
| @b{Members:} |
| @table @asis |
| @item @code{auth: string} (optional) |
| authentication method |
| @item The members of @code{SpiceBasicInfo} |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SpiceChannel |
| |
| Information about a SPICE client channel. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{connection-id: int} |
| SPICE connection id number. All channels with the same id |
| belong to the same SPICE session. |
| @item @code{channel-type: int} |
| SPICE channel type number. "1" is the main control |
| channel, filter for this one if you want to track spice |
| sessions only |
| @item @code{channel-id: int} |
| SPICE channel ID number. Usually "0", might be different when |
| multiple channels of the same type exist, such as multiple |
| display channels in a multihead setup |
| @item @code{tls: boolean} |
| true if the channel is encrypted, false otherwise. |
| @item The members of @code{SpiceBasicInfo} |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} SpiceQueryMouseMode |
| |
| An enumeration of Spice mouse states. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{client} |
| Mouse cursor position is determined by the client. |
| @item @code{server} |
| Mouse cursor position is determined by the server. |
| @item @code{unknown} |
| No information is available about mouse mode used by |
| the spice server. |
| @end table |
| |
| @b{Note:} |
| spice/enums.h has a SpiceMouseMode already, hence the name. |
| |
| @b{Since:} |
| 1.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SpiceInfo |
| |
| Information about the SPICE session. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{enabled: boolean} |
| true if the SPICE server is enabled, false otherwise |
| @item @code{migrated: boolean} |
| true if the last guest migration completed and spice |
| migration had completed as well. false otherwise. (since 1.4) |
| @item @code{host: string} (optional) |
| The hostname the SPICE server is bound to. This depends on |
| the name resolution on the host and may be an IP address. |
| @item @code{port: int} (optional) |
| The SPICE server's port number. |
| @item @code{compiled-version: string} (optional) |
| SPICE server version. |
| @item @code{tls-port: int} (optional) |
| The SPICE server's TLS port number. |
| @item @code{auth: string} (optional) |
| the current authentication type used by the server |
| 'none' if no authentication is being used |
| 'spice' uses SASL or direct TLS authentication, depending on command |
| line options |
| @item @code{mouse-mode: SpiceQueryMouseMode} |
| The mode in which the mouse cursor is displayed currently. Can |
| be determined by the client or the server, or unknown if spice |
| server doesn't provide this information. (since: 1.1) |
| @item @code{channels: array of SpiceChannel} (optional) |
| a list of @code{SpiceChannel} for each active spice channel |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-spice |
| |
| Returns information about the current SPICE server |
| |
| @b{Returns:} |
| @code{SpiceInfo} |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-spice" @} |
| <- @{ "return": @{ |
| "enabled": true, |
| "auth": "spice", |
| "port": 5920, |
| "tls-port": 5921, |
| "host": "0.0.0.0", |
| "channels": [ |
| @{ |
| "port": "54924", |
| "family": "ipv4", |
| "channel-type": 1, |
| "connection-id": 1804289383, |
| "host": "127.0.0.1", |
| "channel-id": 0, |
| "tls": true |
| @}, |
| @{ |
| "port": "36710", |
| "family": "ipv4", |
| "channel-type": 4, |
| "connection-id": 1804289383, |
| "host": "127.0.0.1", |
| "channel-id": 0, |
| "tls": false |
| @}, |
| [ ... more channels follow ... ] |
| ] |
| @} |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} SPICE_CONNECTED |
| |
| Emitted when a SPICE client establishes a connection |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{server: SpiceBasicInfo} |
| server information |
| @item @code{client: SpiceBasicInfo} |
| client information |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "timestamp": @{"seconds": 1290688046, "microseconds": 388707@}, |
| "event": "SPICE_CONNECTED", |
| "data": @{ |
| "server": @{ "port": "5920", "family": "ipv4", "host": "127.0.0.1"@}, |
| "client": @{"port": "52873", "family": "ipv4", "host": "127.0.0.1"@} |
| @}@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} SPICE_INITIALIZED |
| |
| Emitted after initial handshake and authentication takes place (if any) |
| and the SPICE channel is up and running |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{server: SpiceServerInfo} |
| server information |
| @item @code{client: SpiceChannel} |
| client information |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "timestamp": @{"seconds": 1290688046, "microseconds": 417172@}, |
| "event": "SPICE_INITIALIZED", |
| "data": @{"server": @{"auth": "spice", "port": "5921", |
| "family": "ipv4", "host": "127.0.0.1"@}, |
| "client": @{"port": "49004", "family": "ipv4", "channel-type": 3, |
| "connection-id": 1804289383, "host": "127.0.0.1", |
| "channel-id": 0, "tls": true@} |
| @}@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} SPICE_DISCONNECTED |
| |
| Emitted when the SPICE connection is closed |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{server: SpiceBasicInfo} |
| server information |
| @item @code{client: SpiceBasicInfo} |
| client information |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "timestamp": @{"seconds": 1290688046, "microseconds": 388707@}, |
| "event": "SPICE_DISCONNECTED", |
| "data": @{ |
| "server": @{ "port": "5920", "family": "ipv4", "host": "127.0.0.1"@}, |
| "client": @{"port": "52873", "family": "ipv4", "host": "127.0.0.1"@} |
| @}@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} SPICE_MIGRATE_COMPLETED |
| |
| Emitted when SPICE migration has completed |
| |
| @b{Since:} |
| 1.3 |
| |
| @b{Example:} |
| @example |
| <- @{ "timestamp": @{"seconds": 1290688046, "microseconds": 417172@}, |
| "event": "SPICE_MIGRATE_COMPLETED" @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @subsection VNC |
| |
| |
| @deftp {Object} VncBasicInfo |
| |
| The basic information for vnc network connection |
| |
| @b{Members:} |
| @table @asis |
| @item @code{host: string} |
| IP address |
| @item @code{service: string} |
| The service name of the vnc port. This may depend on the host |
| system's service database so symbolic names should not be relied |
| on. |
| @item @code{family: NetworkAddressFamily} |
| address family |
| @item @code{websocket: boolean} |
| true in case the socket is a websocket (since 2.3). |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} VncServerInfo |
| |
| The network connection information for server |
| |
| @b{Members:} |
| @table @asis |
| @item @code{auth: string} (optional) |
| authentication method used for |
| the plain (non-websocket) VNC server |
| @item The members of @code{VncBasicInfo} |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} VncClientInfo |
| |
| Information about a connected VNC client. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{x509_dname: string} (optional) |
| If x509 authentication is in use, the Distinguished |
| Name of the client. |
| @item @code{sasl_username: string} (optional) |
| If SASL authentication is in use, the SASL username |
| used for authentication. |
| @item The members of @code{VncBasicInfo} |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} VncInfo |
| |
| Information about the VNC session. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{enabled: boolean} |
| true if the VNC server is enabled, false otherwise |
| @item @code{host: string} (optional) |
| The hostname the VNC server is bound to. This depends on |
| the name resolution on the host and may be an IP address. |
| @item @code{family: NetworkAddressFamily} (optional) |
| 'ipv6' if the host is listening for IPv6 connections |
| 'ipv4' if the host is listening for IPv4 connections |
| 'unix' if the host is listening on a unix domain socket |
| 'unknown' otherwise |
| @item @code{service: string} (optional) |
| The service name of the server's port. This may depends |
| on the host system's service database so symbolic names should not |
| be relied on. |
| @item @code{auth: string} (optional) |
| the current authentication type used by the server |
| 'none' if no authentication is being used |
| 'vnc' if VNC authentication is being used |
| 'vencrypt+plain' if VEncrypt is used with plain text authentication |
| 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication |
| 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication |
| 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth |
| 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth |
| 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth |
| 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth |
| 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth |
| 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth |
| @item @code{clients: array of VncClientInfo} (optional) |
| a list of @code{VncClientInfo} of all currently connected clients |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} VncPrimaryAuth |
| |
| vnc primary authentication method. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{none} |
| Not documented |
| @item @code{vnc} |
| Not documented |
| @item @code{ra2} |
| Not documented |
| @item @code{ra2ne} |
| Not documented |
| @item @code{tight} |
| Not documented |
| @item @code{ultra} |
| Not documented |
| @item @code{tls} |
| Not documented |
| @item @code{vencrypt} |
| Not documented |
| @item @code{sasl} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} VncVencryptSubAuth |
| |
| vnc sub authentication method with vencrypt. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{plain} |
| Not documented |
| @item @code{tls-none} |
| Not documented |
| @item @code{x509-none} |
| Not documented |
| @item @code{tls-vnc} |
| Not documented |
| @item @code{x509-vnc} |
| Not documented |
| @item @code{tls-plain} |
| Not documented |
| @item @code{x509-plain} |
| Not documented |
| @item @code{tls-sasl} |
| Not documented |
| @item @code{x509-sasl} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} VncServerInfo2 |
| |
| The network connection information for server |
| |
| @b{Members:} |
| @table @asis |
| @item @code{auth: VncPrimaryAuth} |
| The current authentication type used by the servers |
| @item @code{vencrypt: VncVencryptSubAuth} (optional) |
| The vencrypt sub authentication type used by the |
| servers, only specified in case auth == vencrypt. |
| @item The members of @code{VncBasicInfo} |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} VncInfo2 |
| |
| Information about a vnc server |
| |
| @b{Members:} |
| @table @asis |
| @item @code{id: string} |
| vnc server name. |
| @item @code{server: array of VncServerInfo2} |
| A list of @code{VncBasincInfo} describing all listening sockets. |
| The list can be empty (in case the vnc server is disabled). |
| It also may have multiple entries: normal + websocket, |
| possibly also ipv4 + ipv6 in the future. |
| @item @code{clients: array of VncClientInfo} |
| A list of @code{VncClientInfo} of all currently connected clients. |
| The list can be empty, for obvious reasons. |
| @item @code{auth: VncPrimaryAuth} |
| The current authentication type used by the non-websockets servers |
| @item @code{vencrypt: VncVencryptSubAuth} (optional) |
| The vencrypt authentication type used by the servers, |
| only specified in case auth == vencrypt. |
| @item @code{display: string} (optional) |
| The display device the vnc server is linked to. |
| @end table |
| |
| @b{Since:} |
| 2.3 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-vnc |
| |
| Returns information about the current VNC server |
| |
| @b{Returns:} |
| @code{VncInfo} |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-vnc" @} |
| <- @{ "return": @{ |
| "enabled":true, |
| "host":"0.0.0.0", |
| "service":"50402", |
| "auth":"vnc", |
| "family":"ipv4", |
| "clients":[ |
| @{ |
| "host":"127.0.0.1", |
| "service":"50401", |
| "family":"ipv4" |
| @} |
| ] |
| @} |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} query-vnc-servers |
| |
| Returns a list of vnc servers. The list can be empty. |
| |
| @b{Returns:} |
| a list of @code{VncInfo2} |
| |
| @b{Since:} |
| 2.3 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} change-vnc-password |
| |
| Change the VNC server password. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{password: string} |
| the new password to use with VNC authentication |
| @end table |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Notes:} |
| An empty password in this command will set the password to the empty |
| string. Existing clients are unaffected by executing this command. |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} VNC_CONNECTED |
| |
| Emitted when a VNC client establishes a connection |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{server: VncServerInfo} |
| server information |
| @item @code{client: VncBasicInfo} |
| client information |
| @end table |
| |
| @b{Note:} |
| This event is emitted before any authentication takes place, thus |
| the authentication ID is not provided |
| |
| @b{Since:} |
| 0.13.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "VNC_CONNECTED", |
| "data": @{ |
| "server": @{ "auth": "sasl", "family": "ipv4", |
| "service": "5901", "host": "0.0.0.0" @}, |
| "client": @{ "family": "ipv4", "service": "58425", |
| "host": "127.0.0.1" @} @}, |
| "timestamp": @{ "seconds": 1262976601, "microseconds": 975795 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} VNC_INITIALIZED |
| |
| Emitted after authentication takes place (if any) and the VNC session is |
| made active |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{server: VncServerInfo} |
| server information |
| @item @code{client: VncClientInfo} |
| client information |
| @end table |
| |
| @b{Since:} |
| 0.13.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "VNC_INITIALIZED", |
| "data": @{ |
| "server": @{ "auth": "sasl", "family": "ipv4", |
| "service": "5901", "host": "0.0.0.0"@}, |
| "client": @{ "family": "ipv4", "service": "46089", |
| "host": "127.0.0.1", "sasl_username": "luiz" @} @}, |
| "timestamp": @{ "seconds": 1263475302, "microseconds": 150772 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} VNC_DISCONNECTED |
| |
| Emitted when the connection is closed |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{server: VncServerInfo} |
| server information |
| @item @code{client: VncClientInfo} |
| client information |
| @end table |
| |
| @b{Since:} |
| 0.13.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "VNC_DISCONNECTED", |
| "data": @{ |
| "server": @{ "auth": "sasl", "family": "ipv4", |
| "service": "5901", "host": "0.0.0.0" @}, |
| "client": @{ "family": "ipv4", "service": "58425", |
| "host": "127.0.0.1", "sasl_username": "luiz" @} @}, |
| "timestamp": @{ "seconds": 1262976601, "microseconds": 975795 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @section Input |
| |
| |
| @deftp {Object} MouseInfo |
| |
| Information about a mouse device. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| the name of the mouse device |
| @item @code{index: int} |
| the index of the mouse device |
| @item @code{current: boolean} |
| true if this device is currently receiving mouse events |
| @item @code{absolute: boolean} |
| true if this device supports absolute coordinates as input |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-mice |
| |
| Returns information about each active mouse device |
| |
| @b{Returns:} |
| a list of @code{MouseInfo} for each device |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-mice" @} |
| <- @{ "return": [ |
| @{ |
| "name":"QEMU Microsoft Mouse", |
| "index":0, |
| "current":false, |
| "absolute":false |
| @}, |
| @{ |
| "name":"QEMU PS/2 Mouse", |
| "index":1, |
| "current":true, |
| "absolute":true |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} QKeyCode |
| |
| An enumeration of key name. |
| |
| This is used by the @code{send-key} command. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{unmapped} |
| since 2.0 |
| @item @code{pause} |
| since 2.0 |
| @item @code{ro} |
| since 2.4 |
| @item @code{kp_comma} |
| since 2.4 |
| @item @code{kp_equals} |
| since 2.6 |
| @item @code{power} |
| since 2.6 |
| @item @code{hiragana} |
| since 2.9 |
| @item @code{henkan} |
| since 2.9 |
| @item @code{yen} |
| since 2.9 |
| @item @code{sleep} |
| since 2.10 |
| @item @code{wake} |
| since 2.10 |
| @item @code{audionext} |
| since 2.10 |
| @item @code{audioprev} |
| since 2.10 |
| @item @code{audiostop} |
| since 2.10 |
| @item @code{audioplay} |
| since 2.10 |
| @item @code{audiomute} |
| since 2.10 |
| @item @code{volumeup} |
| since 2.10 |
| @item @code{volumedown} |
| since 2.10 |
| @item @code{mediaselect} |
| since 2.10 |
| @item @code{mail} |
| since 2.10 |
| @item @code{calculator} |
| since 2.10 |
| @item @code{computer} |
| since 2.10 |
| @item @code{ac_home} |
| since 2.10 |
| @item @code{ac_back} |
| since 2.10 |
| @item @code{ac_forward} |
| since 2.10 |
| @item @code{ac_refresh} |
| since 2.10 |
| @item @code{ac_bookmarks} |
| since 2.10 |
| altgr, altgr_r: dropped in 2.10 |
| @item @code{muhenkan} |
| since 2.12 |
| @item @code{katakanahiragana} |
| since 2.12 |
| @item @code{shift} |
| Not documented |
| @item @code{shift_r} |
| Not documented |
| @item @code{alt} |
| Not documented |
| @item @code{alt_r} |
| Not documented |
| @item @code{ctrl} |
| Not documented |
| @item @code{ctrl_r} |
| Not documented |
| @item @code{menu} |
| Not documented |
| @item @code{esc} |
| Not documented |
| @item @code{1} |
| Not documented |
| @item @code{2} |
| Not documented |
| @item @code{3} |
| Not documented |
| @item @code{4} |
| Not documented |
| @item @code{5} |
| Not documented |
| @item @code{6} |
| Not documented |
| @item @code{7} |
| Not documented |
| @item @code{8} |
| Not documented |
| @item @code{9} |
| Not documented |
| @item @code{0} |
| Not documented |
| @item @code{minus} |
| Not documented |
| @item @code{equal} |
| Not documented |
| @item @code{backspace} |
| Not documented |
| @item @code{tab} |
| Not documented |
| @item @code{q} |
| Not documented |
| @item @code{w} |
| Not documented |
| @item @code{e} |
| Not documented |
| @item @code{r} |
| Not documented |
| @item @code{t} |
| Not documented |
| @item @code{y} |
| Not documented |
| @item @code{u} |
| Not documented |
| @item @code{i} |
| Not documented |
| @item @code{o} |
| Not documented |
| @item @code{p} |
| Not documented |
| @item @code{bracket_left} |
| Not documented |
| @item @code{bracket_right} |
| Not documented |
| @item @code{ret} |
| Not documented |
| @item @code{a} |
| Not documented |
| @item @code{s} |
| Not documented |
| @item @code{d} |
| Not documented |
| @item @code{f} |
| Not documented |
| @item @code{g} |
| Not documented |
| @item @code{h} |
| Not documented |
| @item @code{j} |
| Not documented |
| @item @code{k} |
| Not documented |
| @item @code{l} |
| Not documented |
| @item @code{semicolon} |
| Not documented |
| @item @code{apostrophe} |
| Not documented |
| @item @code{grave_accent} |
| Not documented |
| @item @code{backslash} |
| Not documented |
| @item @code{z} |
| Not documented |
| @item @code{x} |
| Not documented |
| @item @code{c} |
| Not documented |
| @item @code{v} |
| Not documented |
| @item @code{b} |
| Not documented |
| @item @code{n} |
| Not documented |
| @item @code{m} |
| Not documented |
| @item @code{comma} |
| Not documented |
| @item @code{dot} |
| Not documented |
| @item @code{slash} |
| Not documented |
| @item @code{asterisk} |
| Not documented |
| @item @code{spc} |
| Not documented |
| @item @code{caps_lock} |
| Not documented |
| @item @code{f1} |
| Not documented |
| @item @code{f2} |
| Not documented |
| @item @code{f3} |
| Not documented |
| @item @code{f4} |
| Not documented |
| @item @code{f5} |
| Not documented |
| @item @code{f6} |
| Not documented |
| @item @code{f7} |
| Not documented |
| @item @code{f8} |
| Not documented |
| @item @code{f9} |
| Not documented |
| @item @code{f10} |
| Not documented |
| @item @code{num_lock} |
| Not documented |
| @item @code{scroll_lock} |
| Not documented |
| @item @code{kp_divide} |
| Not documented |
| @item @code{kp_multiply} |
| Not documented |
| @item @code{kp_subtract} |
| Not documented |
| @item @code{kp_add} |
| Not documented |
| @item @code{kp_enter} |
| Not documented |
| @item @code{kp_decimal} |
| Not documented |
| @item @code{sysrq} |
| Not documented |
| @item @code{kp_0} |
| Not documented |
| @item @code{kp_1} |
| Not documented |
| @item @code{kp_2} |
| Not documented |
| @item @code{kp_3} |
| Not documented |
| @item @code{kp_4} |
| Not documented |
| @item @code{kp_5} |
| Not documented |
| @item @code{kp_6} |
| Not documented |
| @item @code{kp_7} |
| Not documented |
| @item @code{kp_8} |
| Not documented |
| @item @code{kp_9} |
| Not documented |
| @item @code{less} |
| Not documented |
| @item @code{f11} |
| Not documented |
| @item @code{f12} |
| Not documented |
| @item @code{print} |
| Not documented |
| @item @code{home} |
| Not documented |
| @item @code{pgup} |
| Not documented |
| @item @code{pgdn} |
| Not documented |
| @item @code{end} |
| Not documented |
| @item @code{left} |
| Not documented |
| @item @code{up} |
| Not documented |
| @item @code{down} |
| Not documented |
| @item @code{right} |
| Not documented |
| @item @code{insert} |
| Not documented |
| @item @code{delete} |
| Not documented |
| @item @code{stop} |
| Not documented |
| @item @code{again} |
| Not documented |
| @item @code{props} |
| Not documented |
| @item @code{undo} |
| Not documented |
| @item @code{front} |
| Not documented |
| @item @code{copy} |
| Not documented |
| @item @code{open} |
| Not documented |
| @item @code{paste} |
| Not documented |
| @item @code{find} |
| Not documented |
| @item @code{cut} |
| Not documented |
| @item @code{lf} |
| Not documented |
| @item @code{help} |
| Not documented |
| @item @code{meta_l} |
| Not documented |
| @item @code{meta_r} |
| Not documented |
| @item @code{compose} |
| Not documented |
| @end table |
| 'sysrq' was mistakenly added to hack around the fact that |
| the ps2 driver was not generating correct scancodes sequences |
| when 'alt+print' was pressed. This flaw is now fixed and the |
| 'sysrq' key serves no further purpose. Any further use of |
| 'sysrq' will be transparently changed to 'print', so they |
| are effectively synonyms. |
| |
| @b{Since:} |
| 1.3.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} KeyValue |
| |
| Represents a keyboard key. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type} |
| One of @t{"number"}, @t{"qcode"} |
| @item @code{data: int} when @code{type} is @t{"number"} |
| @item @code{data: QKeyCode} when @code{type} is @t{"qcode"} |
| @end table |
| |
| @b{Since:} |
| 1.3.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} send-key |
| |
| Send keys to guest. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{keys: array of KeyValue} |
| An array of @code{KeyValue} elements. All @code{KeyValues} in this array are |
| simultaneously sent to the guest. A @code{KeyValue}.number value is sent |
| directly to the guest, while @code{KeyValue}.qcode must be a valid |
| @code{QKeyCode} value |
| @item @code{hold-time: int} (optional) |
| time to delay key up events, milliseconds. Defaults |
| to 100 |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If key is unknown or redundant, InvalidParameter |
| |
| @b{Since:} |
| 1.3.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "send-key", |
| "arguments": @{ "keys": [ @{ "type": "qcode", "data": "ctrl" @}, |
| @{ "type": "qcode", "data": "alt" @}, |
| @{ "type": "qcode", "data": "delete" @} ] @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} InputButton |
| |
| Button of a pointer input device (mouse, tablet). |
| |
| @b{Values:} |
| @table @asis |
| @item @code{side} |
| front side button of a 5-button mouse (since 2.9) |
| @item @code{extra} |
| rear side button of a 5-button mouse (since 2.9) |
| @item @code{left} |
| Not documented |
| @item @code{middle} |
| Not documented |
| @item @code{right} |
| Not documented |
| @item @code{wheel-up} |
| Not documented |
| @item @code{wheel-down} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} InputAxis |
| |
| Position axis of a pointer input device (mouse, tablet). |
| |
| @b{Values:} |
| @table @asis |
| @item @code{x} |
| Not documented |
| @item @code{y} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} InputKeyEvent |
| |
| Keyboard input event. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{key: KeyValue} |
| Which key this event is for. |
| @item @code{down: boolean} |
| True for key-down and false for key-up events. |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} InputBtnEvent |
| |
| Pointer button input event. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{button: InputButton} |
| Which button this event is for. |
| @item @code{down: boolean} |
| True for key-down and false for key-up events. |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} InputMoveEvent |
| |
| Pointer motion input event. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{axis: InputAxis} |
| Which axis is referenced by @code{value}. |
| @item @code{value: int} |
| Pointer position. For absolute coordinates the |
| valid range is 0 -> 0x7ffff |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} InputEvent |
| |
| Input event union. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type} |
| the input type, one of: |
| @itemize @minus |
| @item |
| 'key': Input event of Keyboard |
| @item |
| 'btn': Input event of pointer buttons |
| @item |
| 'rel': Input event of relative pointer motion |
| @item |
| 'abs': Input event of absolute pointer motion |
| @end itemize |
| |
| @item @code{data: InputKeyEvent} when @code{type} is @t{"key"} |
| @item @code{data: InputBtnEvent} when @code{type} is @t{"btn"} |
| @item @code{data: InputMoveEvent} when @code{type} is @t{"rel"} |
| @item @code{data: InputMoveEvent} when @code{type} is @t{"abs"} |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} input-send-event |
| |
| Send input event(s) to guest. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} (optional) |
| display device to send event(s) to. |
| @item @code{head: int} (optional) |
| head to send event(s) to, in case the |
| display device supports multiple scanouts. |
| @item @code{events: array of InputEvent} |
| List of InputEvent union. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success. |
| |
| The @code{device} and @code{head} parameters can be used to send the input event |
| to specific input devices in case (a) multiple input devices of the |
| same kind are added to the virtual machine and (b) you have |
| configured input routing (see docs/multiseat.txt) for those input |
| devices. The parameters work exactly like the device and head |
| properties of input devices. If @code{device} is missing, only devices |
| that have no input routing config are admissible. If @code{device} is |
| specified, both input devices with and without input routing config |
| are admissible, but devices with input routing config take |
| precedence. |
| |
| @b{Since:} |
| 2.6 |
| |
| @b{Note:} |
| The consoles are visible in the qom tree, under |
| /backend/console[$index]. They have a device link and head property, |
| so it is possible to map which console belongs to which device and |
| display. |
| |
| @b{Example:} |
| @example |
| 1. Press left mouse button. |
| |
| -> @{ "execute": "input-send-event", |
| "arguments": @{ "device": "video0", |
| "events": [ @{ "type": "btn", |
| "data" : @{ "down": true, "button": "left" @} @} ] @} @} |
| <- @{ "return": @{@} @} |
| |
| -> @{ "execute": "input-send-event", |
| "arguments": @{ "device": "video0", |
| "events": [ @{ "type": "btn", |
| "data" : @{ "down": false, "button": "left" @} @} ] @} @} |
| <- @{ "return": @{@} @} |
| |
| 2. Press ctrl-alt-del. |
| |
| -> @{ "execute": "input-send-event", |
| "arguments": @{ "events": [ |
| @{ "type": "key", "data" : @{ "down": true, |
| "key": @{"type": "qcode", "data": "ctrl" @} @} @}, |
| @{ "type": "key", "data" : @{ "down": true, |
| "key": @{"type": "qcode", "data": "alt" @} @} @}, |
| @{ "type": "key", "data" : @{ "down": true, |
| "key": @{"type": "qcode", "data": "delete" @} @} @} ] @} @} |
| <- @{ "return": @{@} @} |
| |
| 3. Move mouse pointer to absolute coordinates (20000, 400). |
| |
| -> @{ "execute": "input-send-event" , |
| "arguments": @{ "events": [ |
| @{ "type": "abs", "data" : @{ "axis": "x", "value" : 20000 @} @}, |
| @{ "type": "abs", "data" : @{ "axis": "y", "value" : 400 @} @} ] @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} DisplayNoOpts |
| |
| Empty struct for displays without config options. |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} DisplayGTK |
| |
| GTK display options. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{grab-on-hover: boolean} (optional) |
| Grab keyboard input on mouse hover. |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} DisplayType |
| |
| Display (user interface) type. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{default} |
| Not documented |
| @item @code{none} |
| Not documented |
| @item @code{gtk} |
| Not documented |
| @item @code{sdl} |
| Not documented |
| @item @code{egl-headless} |
| Not documented |
| @item @code{curses} |
| Not documented |
| @item @code{cocoa} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} DisplayOptions |
| |
| Display (user interface) options. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: DisplayType} |
| Which DisplayType qemu should use. |
| @item @code{full-screen: boolean} (optional) |
| Start user interface in fullscreen mode (default: off). |
| @item @code{window-close: boolean} (optional) |
| Allow to quit qemu with window close button (default: on). |
| @item @code{gl: boolean} (optional) |
| Enable OpenGL support (default: off). |
| @item The members of @code{DisplayNoOpts} when @code{type} is @t{"default"} |
| @item The members of @code{DisplayNoOpts} when @code{type} is @t{"none"} |
| @item The members of @code{DisplayGTK} when @code{type} is @t{"gtk"} |
| @item The members of @code{DisplayNoOpts} when @code{type} is @t{"sdl"} |
| @item The members of @code{DisplayNoOpts} when @code{type} is @t{"egl-headless"} |
| @item The members of @code{DisplayNoOpts} when @code{type} is @t{"curses"} |
| @item The members of @code{DisplayNoOpts} when @code{type} is @t{"cocoa"} |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| @section Migration |
| |
| |
| @deftp {Object} MigrationStats |
| |
| Detailed migration status. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{transferred: int} |
| amount of bytes already transferred to the target VM |
| @item @code{remaining: int} |
| amount of bytes remaining to be transferred to the target VM |
| @item @code{total: int} |
| total amount of bytes involved in the migration process |
| @item @code{duplicate: int} |
| number of duplicate (zero) pages (since 1.2) |
| @item @code{skipped: int} |
| number of skipped zero pages (since 1.5) |
| @item @code{normal: int} |
| number of normal pages (since 1.2) |
| @item @code{normal-bytes: int} |
| number of normal bytes sent (since 1.2) |
| @item @code{dirty-pages-rate: int} |
| number of pages dirtied by second by the |
| guest (since 1.3) |
| @item @code{mbps: number} |
| throughput in megabits/sec. (since 1.6) |
| @item @code{dirty-sync-count: int} |
| number of times that dirty ram was synchronized (since 2.1) |
| @item @code{postcopy-requests: int} |
| The number of page requests received from the destination |
| (since 2.7) |
| @item @code{page-size: int} |
| The number of bytes per page for the various page-based |
| statistics (since 2.10) |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} XBZRLECacheStats |
| |
| Detailed XBZRLE migration cache statistics |
| |
| @b{Members:} |
| @table @asis |
| @item @code{cache-size: int} |
| XBZRLE cache size |
| @item @code{bytes: int} |
| amount of bytes already transferred to the target VM |
| @item @code{pages: int} |
| amount of pages transferred to the target VM |
| @item @code{cache-miss: int} |
| number of cache miss |
| @item @code{cache-miss-rate: number} |
| rate of cache miss (since 2.1) |
| @item @code{overflow: int} |
| number of overflows |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} MigrationStatus |
| |
| An enumeration of migration status. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{none} |
| no migration has ever happened. |
| @item @code{setup} |
| migration process has been initiated. |
| @item @code{cancelling} |
| in the process of cancelling migration. |
| @item @code{cancelled} |
| cancelling migration is finished. |
| @item @code{active} |
| in the process of doing migration. |
| @item @code{postcopy-active} |
| like active, but now in postcopy mode. (since 2.5) |
| @item @code{completed} |
| migration is finished. |
| @item @code{failed} |
| some error occurred during migration process. |
| @item @code{colo} |
| VM is in the process of fault tolerance, VM can not get into this |
| state unless colo capability is enabled for migration. (since 2.8) |
| @item @code{pre-switchover} |
| Paused before device serialisation. (since 2.11) |
| @item @code{device} |
| During device serialisation when pause-before-switchover is enabled |
| (since 2.11) |
| @end table |
| |
| @b{Since:} |
| 2.3 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} MigrationInfo |
| |
| Information about current migration process. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{status: MigrationStatus} (optional) |
| @code{MigrationStatus} describing the current migration status. |
| If this field is not returned, no migration process |
| has been initiated |
| @item @code{ram: MigrationStats} (optional) |
| @code{MigrationStats} containing detailed migration |
| status, only returned if status is 'active' or |
| 'completed'(since 1.2) |
| @item @code{disk: MigrationStats} (optional) |
| @code{MigrationStats} containing detailed disk migration |
| status, only returned if status is 'active' and it is a block |
| migration |
| @item @code{xbzrle-cache: XBZRLECacheStats} (optional) |
| @code{XBZRLECacheStats} containing detailed XBZRLE |
| migration statistics, only returned if XBZRLE feature is on and |
| status is 'active' or 'completed' (since 1.2) |
| @item @code{total-time: int} (optional) |
| total amount of milliseconds since migration started. |
| If migration has ended, it returns the total migration |
| time. (since 1.2) |
| @item @code{downtime: int} (optional) |
| only present when migration finishes correctly |
| total downtime in milliseconds for the guest. |
| (since 1.3) |
| @item @code{expected-downtime: int} (optional) |
| only present while migration is active |
| expected downtime in milliseconds for the guest in last walk |
| of the dirty bitmap. (since 1.3) |
| @item @code{setup-time: int} (optional) |
| amount of setup time in milliseconds @emph{before} the |
| iterations begin but @emph{after} the QMP command is issued. This is designed |
| to provide an accounting of any activities (such as RDMA pinning) which |
| may be expensive, but do not actually occur during the iterative |
| migration rounds themselves. (since 1.6) |
| @item @code{cpu-throttle-percentage: int} (optional) |
| percentage of time guest cpus are being |
| throttled during auto-converge. This is only present when auto-converge |
| has started throttling guest cpus. (Since 2.7) |
| @item @code{error-desc: string} (optional) |
| the human readable error description string, when |
| @code{status} is 'failed'. Clients should not attempt to parse the |
| error strings. (Since 2.7) |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-migrate |
| |
| Returns information about current migration process. If migration |
| is active there will be another json-object with RAM migration |
| status and if block migration is active another one with block |
| migration status. |
| |
| @b{Returns:} |
| @code{MigrationInfo} |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| 1. Before the first migration |
| |
| -> @{ "execute": "query-migrate" @} |
| <- @{ "return": @{@} @} |
| |
| 2. Migration is done and has succeeded |
| |
| -> @{ "execute": "query-migrate" @} |
| <- @{ "return": @{ |
| "status": "completed", |
| "ram":@{ |
| "transferred":123, |
| "remaining":123, |
| "total":246, |
| "total-time":12345, |
| "setup-time":12345, |
| "downtime":12345, |
| "duplicate":123, |
| "normal":123, |
| "normal-bytes":123456, |
| "dirty-sync-count":15 |
| @} |
| @} |
| @} |
| |
| 3. Migration is done and has failed |
| |
| -> @{ "execute": "query-migrate" @} |
| <- @{ "return": @{ "status": "failed" @} @} |
| |
| 4. Migration is being performed and is not a block migration: |
| |
| -> @{ "execute": "query-migrate" @} |
| <- @{ |
| "return":@{ |
| "status":"active", |
| "ram":@{ |
| "transferred":123, |
| "remaining":123, |
| "total":246, |
| "total-time":12345, |
| "setup-time":12345, |
| "expected-downtime":12345, |
| "duplicate":123, |
| "normal":123, |
| "normal-bytes":123456, |
| "dirty-sync-count":15 |
| @} |
| @} |
| @} |
| |
| 5. Migration is being performed and is a block migration: |
| |
| -> @{ "execute": "query-migrate" @} |
| <- @{ |
| "return":@{ |
| "status":"active", |
| "ram":@{ |
| "total":1057024, |
| "remaining":1053304, |
| "transferred":3720, |
| "total-time":12345, |
| "setup-time":12345, |
| "expected-downtime":12345, |
| "duplicate":123, |
| "normal":123, |
| "normal-bytes":123456, |
| "dirty-sync-count":15 |
| @}, |
| "disk":@{ |
| "total":20971520, |
| "remaining":20880384, |
| "transferred":91136 |
| @} |
| @} |
| @} |
| |
| 6. Migration is being performed and XBZRLE is active: |
| |
| -> @{ "execute": "query-migrate" @} |
| <- @{ |
| "return":@{ |
| "status":"active", |
| "capabilities" : [ @{ "capability": "xbzrle", "state" : true @} ], |
| "ram":@{ |
| "total":1057024, |
| "remaining":1053304, |
| "transferred":3720, |
| "total-time":12345, |
| "setup-time":12345, |
| "expected-downtime":12345, |
| "duplicate":10, |
| "normal":3333, |
| "normal-bytes":3412992, |
| "dirty-sync-count":15 |
| @}, |
| "xbzrle-cache":@{ |
| "cache-size":67108864, |
| "bytes":20971520, |
| "pages":2444343, |
| "cache-miss":2244, |
| "cache-miss-rate":0.123, |
| "overflow":34434 |
| @} |
| @} |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} MigrationCapability |
| |
| Migration capabilities enumeration |
| |
| @b{Values:} |
| @table @asis |
| @item @code{xbzrle} |
| Migration supports xbzrle (Xor Based Zero Run Length Encoding). |
| This feature allows us to minimize migration traffic for certain work |
| loads, by sending compressed difference of the pages |
| @item @code{rdma-pin-all} |
| Controls whether or not the entire VM memory footprint is |
| mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage. |
| Disabled by default. (since 2.0) |
| @item @code{zero-blocks} |
| During storage migration encode blocks of zeroes efficiently. This |
| essentially saves 1MB of zeroes per block on the wire. Enabling requires |
| source and target VM to support this feature. To enable it is sufficient |
| to enable the capability on the source VM. The feature is disabled by |
| default. (since 1.6) |
| @item @code{compress} |
| Use multiple compression threads to accelerate live migration. |
| This feature can help to reduce the migration traffic, by sending |
| compressed pages. Please note that if compress and xbzrle are both |
| on, compress only takes effect in the ram bulk stage, after that, |
| it will be disabled and only xbzrle takes effect, this can help to |
| minimize migration traffic. The feature is disabled by default. |
| (since 2.4 ) |
| @item @code{events} |
| generate events for each migration state change |
| (since 2.4 ) |
| @item @code{auto-converge} |
| If enabled, QEMU will automatically throttle down the guest |
| to speed up convergence of RAM migration. (since 1.6) |
| @item @code{postcopy-ram} |
| Start executing on the migration target before all of RAM has |
| been migrated, pulling the remaining pages along as needed. The |
| capacity must have the same setting on both source and target |
| or migration will not even start. NOTE: If the migration fails during |
| postcopy the VM will fail. (since 2.6) |
| @item @code{x-colo} |
| If enabled, migration will never end, and the state of the VM on the |
| primary side will be migrated continuously to the VM on secondary |
| side, this process is called COarse-Grain LOck Stepping (COLO) for |
| Non-stop Service. (since 2.8) |
| @item @code{release-ram} |
| if enabled, qemu will free the migrated ram pages on the source |
| during postcopy-ram migration. (since 2.9) |
| @item @code{block} |
| If enabled, QEMU will also migrate the contents of all block |
| devices. Default is disabled. A possible alternative uses |
| mirror jobs to a builtin NBD server on the destination, which |
| offers more flexibility. |
| (Since 2.10) |
| @item @code{return-path} |
| If enabled, migration will use the return path even |
| for precopy. (since 2.10) |
| @item @code{pause-before-switchover} |
| Pause outgoing migration before serialising device |
| state and before disabling block IO (since 2.11) |
| @item @code{x-multifd} |
| Use more than one fd for migration (since 2.11) |
| @item @code{dirty-bitmaps} |
| If enabled, QEMU will migrate named dirty bitmaps. |
| (since 2.12) |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} MigrationCapabilityStatus |
| |
| Migration capability information |
| |
| @b{Members:} |
| @table @asis |
| @item @code{capability: MigrationCapability} |
| capability enum |
| @item @code{state: boolean} |
| capability state bool |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} migrate-set-capabilities |
| |
| Enable/Disable the following migration capabilities (like xbzrle) |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{capabilities: array of MigrationCapabilityStatus} |
| json array of capability modifications to make |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "migrate-set-capabilities" , "arguments": |
| @{ "capabilities": [ @{ "capability": "xbzrle", "state": true @} ] @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} query-migrate-capabilities |
| |
| Returns information about the current migration capabilities status |
| |
| @b{Returns:} |
| @code{MigrationCapabilitiesStatus} |
| |
| @b{Since:} |
| 1.2 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-migrate-capabilities" @} |
| <- @{ "return": [ |
| @{"state": false, "capability": "xbzrle"@}, |
| @{"state": false, "capability": "rdma-pin-all"@}, |
| @{"state": false, "capability": "auto-converge"@}, |
| @{"state": false, "capability": "zero-blocks"@}, |
| @{"state": false, "capability": "compress"@}, |
| @{"state": true, "capability": "events"@}, |
| @{"state": false, "capability": "postcopy-ram"@}, |
| @{"state": false, "capability": "x-colo"@} |
| ]@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} MigrationParameter |
| |
| Migration parameters enumeration |
| |
| @b{Values:} |
| @table @asis |
| @item @code{compress-level} |
| Set the compression level to be used in live migration, |
| the compression level is an integer between 0 and 9, where 0 means |
| no compression, 1 means the best compression speed, and 9 means best |
| compression ratio which will consume more CPU. |
| @item @code{compress-threads} |
| Set compression thread count to be used in live migration, |
| the compression thread count is an integer between 1 and 255. |
| @item @code{decompress-threads} |
| Set decompression thread count to be used in live |
| migration, the decompression thread count is an integer between 1 |
| and 255. Usually, decompression is at least 4 times as fast as |
| compression, so set the decompress-threads to the number about 1/4 |
| of compress-threads is adequate. |
| @item @code{cpu-throttle-initial} |
| Initial percentage of time guest cpus are throttled |
| when migration auto-converge is activated. The |
| default value is 20. (Since 2.7) |
| @item @code{cpu-throttle-increment} |
| throttle percentage increase each time |
| auto-converge detects that migration is not making |
| progress. The default value is 10. (Since 2.7) |
| @item @code{tls-creds} |
| ID of the 'tls-creds' object that provides credentials for |
| establishing a TLS connection over the migration data channel. |
| On the outgoing side of the migration, the credentials must |
| be for a 'client' endpoint, while for the incoming side the |
| credentials must be for a 'server' endpoint. Setting this |
| will enable TLS for all migrations. The default is unset, |
| resulting in unsecured migration at the QEMU level. (Since 2.7) |
| @item @code{tls-hostname} |
| hostname of the target host for the migration. This is |
| required when using x509 based TLS credentials and the |
| migration URI does not already include a hostname. For |
| example if using fd: or exec: based migration, the |
| hostname must be provided so that the server's x509 |
| certificate identity can be validated. (Since 2.7) |
| @item @code{max-bandwidth} |
| to set maximum speed for migration. maximum speed in |
| bytes per second. (Since 2.8) |
| @item @code{downtime-limit} |
| set maximum tolerated downtime for migration. maximum |
| downtime in milliseconds (Since 2.8) |
| @item @code{x-checkpoint-delay} |
| The delay time (in ms) between two COLO checkpoints in |
| periodic mode. (Since 2.8) |
| @item @code{block-incremental} |
| Affects how much storage is migrated when the |
| block migration capability is enabled. When false, the entire |
| storage backing chain is migrated into a flattened image at |
| the destination; when true, only the active qcow2 layer is |
| migrated and the destination must already have access to the |
| same backing chain as was used on the source. (since 2.10) |
| @item @code{x-multifd-channels} |
| Number of channels used to migrate data in |
| parallel. This is the same number that the |
| number of sockets used for migration. The |
| default value is 2 (since 2.11) |
| @item @code{x-multifd-page-count} |
| Number of pages sent together to a thread. |
| The default value is 16 (since 2.11) |
| @item @code{xbzrle-cache-size} |
| cache size to be used by XBZRLE migration. It |
| needs to be a multiple of the target page size |
| and a power of 2 |
| (Since 2.11) |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} MigrateSetParameters |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{compress-level: int} (optional) |
| compression level |
| @item @code{compress-threads: int} (optional) |
| compression thread count |
| @item @code{decompress-threads: int} (optional) |
| decompression thread count |
| @item @code{cpu-throttle-initial: int} (optional) |
| Initial percentage of time guest cpus are |
| throttled when migration auto-converge is activated. |
| The default value is 20. (Since 2.7) |
| @item @code{cpu-throttle-increment: int} (optional) |
| throttle percentage increase each time |
| auto-converge detects that migration is not making |
| progress. The default value is 10. (Since 2.7) |
| @item @code{tls-creds: StrOrNull} (optional) |
| ID of the 'tls-creds' object that provides credentials |
| for establishing a TLS connection over the migration data |
| channel. On the outgoing side of the migration, the credentials |
| must be for a 'client' endpoint, while for the incoming side the |
| credentials must be for a 'server' endpoint. Setting this |
| to a non-empty string enables TLS for all migrations. |
| An empty string means that QEMU will use plain text mode for |
| migration, rather than TLS (Since 2.9) |
| Previously (since 2.7), this was reported by omitting |
| tls-creds instead. |
| @item @code{tls-hostname: StrOrNull} (optional) |
| hostname of the target host for the migration. This |
| is required when using x509 based TLS credentials and the |
| migration URI does not already include a hostname. For |
| example if using fd: or exec: based migration, the |
| hostname must be provided so that the server's x509 |
| certificate identity can be validated. (Since 2.7) |
| An empty string means that QEMU will use the hostname |
| associated with the migration URI, if any. (Since 2.9) |
| Previously (since 2.7), this was reported by omitting |
| tls-hostname instead. |
| @item @code{max-bandwidth: int} (optional) |
| to set maximum speed for migration. maximum speed in |
| bytes per second. (Since 2.8) |
| @item @code{downtime-limit: int} (optional) |
| set maximum tolerated downtime for migration. maximum |
| downtime in milliseconds (Since 2.8) |
| @item @code{x-checkpoint-delay: int} (optional) |
| the delay time between two COLO checkpoints. (Since 2.8) |
| @item @code{block-incremental: boolean} (optional) |
| Affects how much storage is migrated when the |
| block migration capability is enabled. When false, the entire |
| storage backing chain is migrated into a flattened image at |
| the destination; when true, only the active qcow2 layer is |
| migrated and the destination must already have access to the |
| same backing chain as was used on the source. (since 2.10) |
| @item @code{x-multifd-channels: int} (optional) |
| Number of channels used to migrate data in |
| parallel. This is the same number that the |
| number of sockets used for migration. The |
| default value is 2 (since 2.11) |
| @item @code{x-multifd-page-count: int} (optional) |
| Number of pages sent together to a thread. |
| The default value is 16 (since 2.11) |
| @item @code{xbzrle-cache-size: int} (optional) |
| cache size to be used by XBZRLE migration. It |
| needs to be a multiple of the target page size |
| and a power of 2 |
| (Since 2.11) |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} migrate-set-parameters |
| |
| Set various migration parameters. |
| |
| @b{Arguments:} the members of @code{MigrateSetParameters} |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "migrate-set-parameters" , |
| "arguments": @{ "compress-level": 1 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} MigrationParameters |
| |
| The optional members aren't actually optional. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{compress-level: int} (optional) |
| compression level |
| @item @code{compress-threads: int} (optional) |
| compression thread count |
| @item @code{decompress-threads: int} (optional) |
| decompression thread count |
| @item @code{cpu-throttle-initial: int} (optional) |
| Initial percentage of time guest cpus are |
| throttled when migration auto-converge is activated. |
| (Since 2.7) |
| @item @code{cpu-throttle-increment: int} (optional) |
| throttle percentage increase each time |
| auto-converge detects that migration is not making |
| progress. (Since 2.7) |
| @item @code{tls-creds: string} (optional) |
| ID of the 'tls-creds' object that provides credentials |
| for establishing a TLS connection over the migration data |
| channel. On the outgoing side of the migration, the credentials |
| must be for a 'client' endpoint, while for the incoming side the |
| credentials must be for a 'server' endpoint. |
| An empty string means that QEMU will use plain text mode for |
| migration, rather than TLS (Since 2.7) |
| Note: 2.8 reports this by omitting tls-creds instead. |
| @item @code{tls-hostname: string} (optional) |
| hostname of the target host for the migration. This |
| is required when using x509 based TLS credentials and the |
| migration URI does not already include a hostname. For |
| example if using fd: or exec: based migration, the |
| hostname must be provided so that the server's x509 |
| certificate identity can be validated. (Since 2.7) |
| An empty string means that QEMU will use the hostname |
| associated with the migration URI, if any. (Since 2.9) |
| Note: 2.8 reports this by omitting tls-hostname instead. |
| @item @code{max-bandwidth: int} (optional) |
| to set maximum speed for migration. maximum speed in |
| bytes per second. (Since 2.8) |
| @item @code{downtime-limit: int} (optional) |
| set maximum tolerated downtime for migration. maximum |
| downtime in milliseconds (Since 2.8) |
| @item @code{x-checkpoint-delay: int} (optional) |
| the delay time between two COLO checkpoints. (Since 2.8) |
| @item @code{block-incremental: boolean} (optional) |
| Affects how much storage is migrated when the |
| block migration capability is enabled. When false, the entire |
| storage backing chain is migrated into a flattened image at |
| the destination; when true, only the active qcow2 layer is |
| migrated and the destination must already have access to the |
| same backing chain as was used on the source. (since 2.10) |
| @item @code{x-multifd-channels: int} (optional) |
| Number of channels used to migrate data in |
| parallel. This is the same number that the |
| number of sockets used for migration. |
| The default value is 2 (since 2.11) |
| @item @code{x-multifd-page-count: int} (optional) |
| Number of pages sent together to a thread. |
| The default value is 16 (since 2.11) |
| @item @code{xbzrle-cache-size: int} (optional) |
| cache size to be used by XBZRLE migration. It |
| needs to be a multiple of the target page size |
| and a power of 2 |
| (Since 2.11) |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-migrate-parameters |
| |
| Returns information about the current migration parameters |
| |
| @b{Returns:} |
| @code{MigrationParameters} |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-migrate-parameters" @} |
| <- @{ "return": @{ |
| "decompress-threads": 2, |
| "cpu-throttle-increment": 10, |
| "compress-threads": 8, |
| "compress-level": 1, |
| "cpu-throttle-initial": 20, |
| "max-bandwidth": 33554432, |
| "downtime-limit": 300 |
| @} |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} client_migrate_info |
| |
| Set migration information for remote display. This makes the server |
| ask the client to automatically reconnect using the new parameters |
| once migration finished successfully. Only implemented for SPICE. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{protocol: string} |
| must be "spice" |
| @item @code{hostname: string} |
| migration target hostname |
| @item @code{port: int} (optional) |
| spice tcp port for plaintext channels |
| @item @code{tls-port: int} (optional) |
| spice tcp port for tls-secured channels |
| @item @code{cert-subject: string} (optional) |
| server certificate subject |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "client_migrate_info", |
| "arguments": @{ "protocol": "spice", |
| "hostname": "virt42.lab.kraxel.org", |
| "port": 1234 @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} migrate-start-postcopy |
| |
| Followup to a migration command to switch the migration to postcopy mode. |
| The postcopy-ram capability must be set on both source and destination |
| before the original migration command. |
| |
| @b{Since:} |
| 2.5 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "migrate-start-postcopy" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} MIGRATION |
| |
| Emitted when a migration event happens |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{status: MigrationStatus} |
| @code{MigrationStatus} describing the current migration status. |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| <- @{"timestamp": @{"seconds": 1432121972, "microseconds": 744001@}, |
| "event": "MIGRATION", |
| "data": @{"status": "completed"@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} MIGRATION_PASS |
| |
| Emitted from the source side of a migration at the start of each pass |
| (when it syncs the dirty bitmap) |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{pass: int} |
| An incrementing count (starting at 1 on the first pass) |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @b{Example:} |
| @example |
| @{ "timestamp": @{"seconds": 1449669631, "microseconds": 239225@}, |
| "event": "MIGRATION_PASS", "data": @{"pass": 2@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} COLOMessage |
| |
| The message transmission between Primary side and Secondary side. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{checkpoint-ready} |
| Secondary VM (SVM) is ready for checkpointing |
| @item @code{checkpoint-request} |
| Primary VM (PVM) tells SVM to prepare for checkpointing |
| @item @code{checkpoint-reply} |
| SVM gets PVM's checkpoint request |
| @item @code{vmstate-send} |
| VM's state will be sent by PVM. |
| @item @code{vmstate-size} |
| The total size of VMstate. |
| @item @code{vmstate-received} |
| VM's state has been received by SVM. |
| @item @code{vmstate-loaded} |
| VM's state has been loaded by SVM. |
| @end table |
| |
| @b{Since:} |
| 2.8 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} COLOMode |
| |
| The colo mode |
| |
| @b{Values:} |
| @table @asis |
| @item @code{unknown} |
| unknown mode |
| @item @code{primary} |
| master side |
| @item @code{secondary} |
| slave side |
| @end table |
| |
| @b{Since:} |
| 2.8 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} FailoverStatus |
| |
| An enumeration of COLO failover status |
| |
| @b{Values:} |
| @table @asis |
| @item @code{none} |
| no failover has ever happened |
| @item @code{require} |
| got failover requirement but not handled |
| @item @code{active} |
| in the process of doing failover |
| @item @code{completed} |
| finish the process of failover |
| @item @code{relaunch} |
| restart the failover process, from 'none' -> 'completed' (Since 2.9) |
| @end table |
| |
| @b{Since:} |
| 2.8 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} x-colo-lost-heartbeat |
| |
| Tell qemu that heartbeat is lost, request it to do takeover procedures. |
| If this command is sent to the PVM, the Primary side will exit COLO mode. |
| If sent to the Secondary, the Secondary side will run failover work, |
| then takes over server operation to become the service VM. |
| |
| @b{Since:} |
| 2.8 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "x-colo-lost-heartbeat" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} migrate_cancel |
| |
| Cancel the current executing migration process. |
| |
| @b{Returns:} |
| nothing on success |
| |
| @b{Notes:} |
| This command succeeds even if there is no migration process running. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "migrate_cancel" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} migrate-continue |
| |
| Continue migration when it's in a paused state. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{state: MigrationStatus} |
| The state the migration is currently expected to be in |
| @end table |
| |
| @b{Returns:} |
| nothing on success |
| |
| @b{Since:} |
| 2.11 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "migrate-continue" , "arguments": |
| @{ "state": "pre-switchover" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} migrate_set_downtime |
| |
| Set maximum tolerated downtime for migration. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{value: number} |
| maximum downtime in seconds |
| @end table |
| |
| @b{Returns:} |
| nothing on success |
| |
| @b{Notes:} |
| This command is deprecated in favor of 'migrate-set-parameters' |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "migrate_set_downtime", "arguments": @{ "value": 0.1 @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} migrate_set_speed |
| |
| Set maximum speed for migration. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{value: int} |
| maximum speed in bytes per second. |
| @end table |
| |
| @b{Returns:} |
| nothing on success |
| |
| @b{Notes:} |
| This command is deprecated in favor of 'migrate-set-parameters' |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "migrate_set_speed", "arguments": @{ "value": 1024 @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} migrate-set-cache-size |
| |
| Set cache size to be used by XBZRLE migration |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{value: int} |
| cache size in bytes |
| @end table |
| The size will be rounded down to the nearest power of 2. |
| The cache size can be modified before and during ongoing migration |
| |
| @b{Returns:} |
| nothing on success |
| |
| @b{Notes:} |
| This command is deprecated in favor of 'migrate-set-parameters' |
| |
| @b{Since:} |
| 1.2 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "migrate-set-cache-size", |
| "arguments": @{ "value": 536870912 @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} query-migrate-cache-size |
| |
| Query migration XBZRLE cache size |
| |
| @b{Returns:} |
| XBZRLE cache size in bytes |
| |
| @b{Notes:} |
| This command is deprecated in favor of 'query-migrate-parameters' |
| |
| @b{Since:} |
| 1.2 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-migrate-cache-size" @} |
| <- @{ "return": 67108864 @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} migrate |
| |
| Migrates the current running guest to another Virtual Machine. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{uri: string} |
| the Uniform Resource Identifier of the destination VM |
| @item @code{blk: boolean} (optional) |
| do block migration (full disk copy) |
| @item @code{inc: boolean} (optional) |
| incremental disk copy migration |
| @item @code{detach: boolean} (optional) |
| this argument exists only for compatibility reasons and |
| is ignored by QEMU |
| @end table |
| |
| @b{Returns:} |
| nothing on success |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| @enumerate |
| @item |
| The 'query-migrate' command should be used to check migration's progress |
| and final result (this information is provided by the 'status' member) |
| |
| @item |
| All boolean arguments default to false |
| |
| @item |
| The user Monitor's "detach" argument is invalid in QMP and should not |
| be used |
| @end enumerate |
| |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "migrate", "arguments": @{ "uri": "tcp:0:4446" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} migrate-incoming |
| |
| Start an incoming migration, the qemu must have been started |
| with -incoming defer |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{uri: string} |
| The Uniform Resource Identifier identifying the source or |
| address to listen on |
| @end table |
| |
| @b{Returns:} |
| nothing on success |
| |
| @b{Since:} |
| 2.3 |
| |
| @b{Notes:} |
| @enumerate |
| @item |
| It's a bad idea to use a string for the uri, but it needs to stay |
| compatible with -incoming and the format of the uri is already exposed |
| above libvirt. |
| |
| @item |
| QEMU must be started with -incoming defer to allow migrate-incoming to |
| be used. |
| |
| @item |
| The uri format is the same as for -incoming |
| @end enumerate |
| |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "migrate-incoming", |
| "arguments": @{ "uri": "tcp::4446" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} xen-save-devices-state |
| |
| Save the state of all devices to file. The RAM and the block devices |
| of the VM are not saved by this command. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{filename: string} |
| the file to save the state of the devices to as binary |
| data. See xen-save-devices-state.txt for a description of the binary |
| format. |
| @item @code{live: boolean} (optional) |
| Optional argument to ask QEMU to treat this command as part of a live |
| migration. Default to true. (since 2.11) |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "xen-save-devices-state", |
| "arguments": @{ "filename": "/tmp/save" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} xen-set-replication |
| |
| Enable or disable replication. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{enable: boolean} |
| true to enable, false to disable. |
| @item @code{primary: boolean} |
| true for primary or false for secondary. |
| @item @code{failover: boolean} (optional) |
| true to do failover, false to stop. but cannot be |
| specified if 'enable' is true. default value is false. |
| @end table |
| |
| @b{Returns:} |
| nothing. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "xen-set-replication", |
| "arguments": @{"enable": true, "primary": false@} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} ReplicationStatus |
| |
| The result format for 'query-xen-replication-status'. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{error: boolean} |
| true if an error happened, false if replication is normal. |
| @item @code{desc: string} (optional) |
| the human readable error description string, when |
| @code{error} is 'true'. |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-xen-replication-status |
| |
| Query replication status while the vm is running. |
| |
| @b{Returns:} |
| A @code{ReplicationResult} object showing the status. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-xen-replication-status" @} |
| <- @{ "return": @{ "error": false @} @} |
| @end example |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} xen-colo-do-checkpoint |
| |
| Xen uses this command to notify replication to trigger a checkpoint. |
| |
| @b{Returns:} |
| nothing. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "xen-colo-do-checkpoint" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftypefn |
| |
| |
| @section Transactions |
| |
| |
| @deftp {Object} Abort |
| |
| This action can be used to test transaction failure. |
| |
| @b{Since:} |
| 1.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} ActionCompletionMode |
| |
| An enumeration of Transactional completion modes. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{individual} |
| Do not attempt to cancel any other Actions if any Actions fail |
| after the Transaction request succeeds. All Actions that |
| can complete successfully will do so without waiting on others. |
| This is the default. |
| @item @code{grouped} |
| If any Action fails after the Transaction succeeds, cancel all |
| Actions. Actions do not complete until all Actions are ready to |
| complete. May be rejected by Actions that do not support this |
| completion mode. |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} TransactionAction |
| |
| A discriminated record of operations that can be performed with |
| @code{transaction}. Action @code{type} can be: |
| |
| @itemize @minus |
| @item |
| @code{abort}: since 1.6 |
| @item |
| @code{block-dirty-bitmap-add}: since 2.5 |
| @item |
| @code{block-dirty-bitmap-clear}: since 2.5 |
| @item |
| @code{blockdev-backup}: since 2.3 |
| @item |
| @code{blockdev-snapshot}: since 2.5 |
| @item |
| @code{blockdev-snapshot-internal-sync}: since 1.7 |
| @item |
| @code{blockdev-snapshot-sync}: since 1.1 |
| @item |
| @code{drive-backup}: since 1.6 |
| @end itemize |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type} |
| One of @t{"abort"}, @t{"block-dirty-bitmap-add"}, @t{"block-dirty-bitmap-clear"}, @t{"blockdev-backup"}, @t{"blockdev-snapshot"}, @t{"blockdev-snapshot-internal-sync"}, @t{"blockdev-snapshot-sync"}, @t{"drive-backup"} |
| @item @code{data: Abort} when @code{type} is @t{"abort"} |
| @item @code{data: BlockDirtyBitmapAdd} when @code{type} is @t{"block-dirty-bitmap-add"} |
| @item @code{data: BlockDirtyBitmap} when @code{type} is @t{"block-dirty-bitmap-clear"} |
| @item @code{data: BlockdevBackup} when @code{type} is @t{"blockdev-backup"} |
| @item @code{data: BlockdevSnapshot} when @code{type} is @t{"blockdev-snapshot"} |
| @item @code{data: BlockdevSnapshotInternal} when @code{type} is @t{"blockdev-snapshot-internal-sync"} |
| @item @code{data: BlockdevSnapshotSync} when @code{type} is @t{"blockdev-snapshot-sync"} |
| @item @code{data: DriveBackup} when @code{type} is @t{"drive-backup"} |
| @end table |
| |
| @b{Since:} |
| 1.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} TransactionProperties |
| |
| Optional arguments to modify the behavior of a Transaction. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{completion-mode: ActionCompletionMode} (optional) |
| Controls how jobs launched asynchronously by |
| Actions will complete or fail as a group. |
| See @code{ActionCompletionMode} for details. |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} transaction |
| |
| Executes a number of transactionable QMP commands atomically. If any |
| operation fails, then the entire set of actions will be abandoned and the |
| appropriate error returned. |
| |
| For external snapshots, the dictionary contains the device, the file to use for |
| the new snapshot, and the format. The default format, if not specified, is |
| qcow2. |
| |
| Each new snapshot defaults to being created by QEMU (wiping any |
| contents if the file already exists), but it is also possible to reuse |
| an externally-created file. In the latter case, you should ensure that |
| the new image file has the same contents as the current one; QEMU cannot |
| perform any meaningful check. Typically this is achieved by using the |
| current image file as the backing file for the new image. |
| |
| On failure, the original disks pre-snapshot attempt will be used. |
| |
| For internal snapshots, the dictionary contains the device and the snapshot's |
| name. If an internal snapshot matching name already exists, the request will |
| be rejected. Only some image formats support it, for example, qcow2, rbd, |
| and sheepdog. |
| |
| On failure, qemu will try delete the newly created internal snapshot in the |
| transaction. When an I/O error occurs during deletion, the user needs to fix |
| it later with qemu-img or other command. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{actions: array of TransactionAction} |
| List of @code{TransactionAction}; |
| information needed for the respective operations. |
| @item @code{properties: TransactionProperties} (optional) |
| structure of additional options to control the |
| execution of the transaction. See @code{TransactionProperties} |
| for additional detail. |
| @end table |
| |
| @b{Returns:} |
| nothing on success |
| |
| Errors depend on the operations of the transaction |
| |
| @b{Note:} |
| The transaction aborts on the first failure. Therefore, there will be |
| information on only one failed operation returned in an error condition, and |
| subsequent actions will not have been attempted. |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "transaction", |
| "arguments": @{ "actions": [ |
| @{ "type": "blockdev-snapshot-sync", "data" : @{ "device": "ide-hd0", |
| "snapshot-file": "/some/place/my-image", |
| "format": "qcow2" @} @}, |
| @{ "type": "blockdev-snapshot-sync", "data" : @{ "node-name": "myfile", |
| "snapshot-file": "/some/place/my-image2", |
| "snapshot-node-name": "node3432", |
| "mode": "existing", |
| "format": "qcow2" @} @}, |
| @{ "type": "blockdev-snapshot-sync", "data" : @{ "device": "ide-hd1", |
| "snapshot-file": "/some/place/my-image2", |
| "mode": "existing", |
| "format": "qcow2" @} @}, |
| @{ "type": "blockdev-snapshot-internal-sync", "data" : @{ |
| "device": "ide-hd2", |
| "name": "snapshot0" @} @} ] @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @section Tracing |
| |
| |
| @deftp {Enum} TraceEventState |
| |
| State of a tracing event. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{unavailable} |
| The event is statically disabled. |
| @item @code{disabled} |
| The event is dynamically disabled. |
| @item @code{enabled} |
| The event is dynamically enabled. |
| @end table |
| |
| @b{Since:} |
| 2.2 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} TraceEventInfo |
| |
| Information of a tracing event. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| Event name. |
| @item @code{state: TraceEventState} |
| Tracing state. |
| @item @code{vcpu: boolean} |
| Whether this is a per-vCPU event (since 2.7). |
| @end table |
| An event is per-vCPU if it has the "vcpu" property in the "trace-events" |
| files. |
| |
| @b{Since:} |
| 2.2 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} trace-event-get-state |
| |
| Query the state of events. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{name: string} |
| Event name pattern (case-sensitive glob). |
| @item @code{vcpu: int} (optional) |
| The vCPU to query (any by default; since 2.7). |
| @end table |
| |
| @b{Returns:} |
| a list of @code{TraceEventInfo} for the matching events |
| |
| An event is returned if: |
| @itemize @minus |
| @item |
| its name matches the @code{name} pattern, and |
| @item |
| if @code{vcpu} is given, the event has the "vcpu" property. |
| |
| @end itemize |
| |
| Therefore, if @code{vcpu} is given, the operation will only match per-vCPU events, |
| returning their state on the specified vCPU. Special case: if @code{name} is an |
| exact match, @code{vcpu} is given and the event does not have the "vcpu" property, |
| an error is returned. |
| |
| @b{Since:} |
| 2.2 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "trace-event-get-state", |
| "arguments": @{ "name": "qemu_memalign" @} @} |
| <- @{ "return": [ @{ "name": "qemu_memalign", "state": "disabled" @} ] @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} trace-event-set-state |
| |
| Set the dynamic tracing state of events. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{name: string} |
| Event name pattern (case-sensitive glob). |
| @item @code{enable: boolean} |
| Whether to enable tracing. |
| @item @code{ignore-unavailable: boolean} (optional) |
| Do not match unavailable events with @code{name}. |
| @item @code{vcpu: int} (optional) |
| The vCPU to act upon (all by default; since 2.7). |
| @end table |
| An event's state is modified if: |
| @itemize @minus |
| @item |
| its name matches the @code{name} pattern, and |
| @item |
| if @code{vcpu} is given, the event has the "vcpu" property. |
| |
| @end itemize |
| |
| Therefore, if @code{vcpu} is given, the operation will only match per-vCPU events, |
| setting their state on the specified vCPU. Special case: if @code{name} is an exact |
| match, @code{vcpu} is given and the event does not have the "vcpu" property, an |
| error is returned. |
| |
| @b{Since:} |
| 2.2 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "trace-event-set-state", |
| "arguments": @{ "name": "qemu_memalign", "enable": "true" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| @section QMP introspection |
| |
| |
| @deftypefn Command {} query-qmp-schema |
| |
| Command query-qmp-schema exposes the QMP wire ABI as an array of |
| SchemaInfo. This lets QMP clients figure out what commands and |
| events are available in this QEMU, and their parameters and results. |
| |
| However, the SchemaInfo can't reflect all the rules and restrictions |
| that apply to QMP. It's interface introspection (figuring out |
| what's there), not interface specification. The specification is in |
| the QAPI schema. |
| |
| Furthermore, while we strive to keep the QMP wire format |
| backwards-compatible across qemu versions, the introspection output |
| is not guaranteed to have the same stability. For example, one |
| version of qemu may list an object member as an optional |
| non-variant, while another lists the same member only through the |
| object's variants; or the type of a member may change from a generic |
| string into a specific enum or from one specific type into an |
| alternate that includes the original type alongside something else. |
| |
| @b{Returns:} |
| array of @code{SchemaInfo}, where each element describes an |
| entity in the ABI: command, event, type, ... |
| |
| The order of the various SchemaInfo is unspecified; however, all |
| names are guaranteed to be unique (no name will be duplicated with |
| different meta-types). |
| |
| @b{Note:} |
| the QAPI schema is also used to help define @strong{internal} |
| interfaces, by defining QAPI types. These are not part of the QMP |
| wire ABI, and therefore not returned by this command. |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} SchemaMetaType |
| |
| This is a @code{SchemaInfo}'s meta type, i.e. the kind of entity it |
| describes. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{builtin} |
| a predefined type such as 'int' or 'bool'. |
| @item @code{enum} |
| an enumeration type |
| @item @code{array} |
| an array type |
| @item @code{object} |
| an object type (struct or union) |
| @item @code{alternate} |
| an alternate type |
| @item @code{command} |
| a QMP command |
| @item @code{event} |
| a QMP event |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfo |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| the entity's name, inherited from @code{base}. |
| The SchemaInfo is always referenced by this name. |
| Commands and events have the name defined in the QAPI schema. |
| Unlike command and event names, type names are not part of |
| the wire ABI. Consequently, type names are meaningless |
| strings here, although they are still guaranteed unique |
| regardless of @code{meta-type}. |
| @item @code{meta-type: SchemaMetaType} |
| the entity's meta type, inherited from @code{base}. |
| @item The members of @code{SchemaInfoBuiltin} when @code{meta-type} is @t{"builtin"} |
| @item The members of @code{SchemaInfoEnum} when @code{meta-type} is @t{"enum"} |
| @item The members of @code{SchemaInfoArray} when @code{meta-type} is @t{"array"} |
| @item The members of @code{SchemaInfoObject} when @code{meta-type} is @t{"object"} |
| @item The members of @code{SchemaInfoAlternate} when @code{meta-type} is @t{"alternate"} |
| @item The members of @code{SchemaInfoCommand} when @code{meta-type} is @t{"command"} |
| @item The members of @code{SchemaInfoEvent} when @code{meta-type} is @t{"event"} |
| @end table |
| Additional members depend on the value of @code{meta-type}. |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfoBuiltin |
| |
| Additional SchemaInfo members for meta-type 'builtin'. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{json-type: JSONType} |
| the JSON type used for this type on the wire. |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} JSONType |
| |
| The four primitive and two structured types according to RFC 7159 |
| section 1, plus 'int' (split off 'number'), plus the obvious top |
| type 'value'. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{string} |
| Not documented |
| @item @code{number} |
| Not documented |
| @item @code{int} |
| Not documented |
| @item @code{boolean} |
| Not documented |
| @item @code{null} |
| Not documented |
| @item @code{object} |
| Not documented |
| @item @code{array} |
| Not documented |
| @item @code{value} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfoEnum |
| |
| Additional SchemaInfo members for meta-type 'enum'. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{values: array of string} |
| the enumeration type's values, in no particular order. |
| @end table |
| Values of this type are JSON string on the wire. |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfoArray |
| |
| Additional SchemaInfo members for meta-type 'array'. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{element-type: string} |
| the array type's element type. |
| @end table |
| Values of this type are JSON array on the wire. |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfoObject |
| |
| Additional SchemaInfo members for meta-type 'object'. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{members: array of SchemaInfoObjectMember} |
| the object type's (non-variant) members, in no particular order. |
| @item @code{tag: string} (optional) |
| the name of the member serving as type tag. |
| An element of @code{members} with this name must exist. |
| @item @code{variants: array of SchemaInfoObjectVariant} (optional) |
| variant members, i.e. additional members that |
| depend on the type tag's value. Present exactly when |
| @code{tag} is present. The variants are in no particular order, |
| and may even differ from the order of the values of the |
| enum type of the @code{tag}. |
| @end table |
| Values of this type are JSON object on the wire. |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfoObjectMember |
| |
| An object member. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| the member's name, as defined in the QAPI schema. |
| @item @code{type: string} |
| the name of the member's type. |
| @item @code{default: value} (optional) |
| default when used as command parameter. |
| If absent, the parameter is mandatory. |
| If present, the value must be null. The parameter is |
| optional, and behavior when it's missing is not specified |
| here. |
| Future extension: if present and non-null, the parameter |
| is optional, and defaults to this value. |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfoObjectVariant |
| |
| The variant members for a value of the type tag. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{case: string} |
| a value of the type tag. |
| @item @code{type: string} |
| the name of the object type that provides the variant members |
| when the type tag has value @code{case}. |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfoAlternate |
| |
| Additional SchemaInfo members for meta-type 'alternate'. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{members: array of SchemaInfoAlternateMember} |
| the alternate type's members, in no particular order. |
| The members' wire encoding is distinct, see |
| docs/devel/qapi-code-gen.txt section Alternate types. |
| @end table |
| On the wire, this can be any of the members. |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfoAlternateMember |
| |
| An alternate member. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: string} |
| the name of the member's type. |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfoCommand |
| |
| Additional SchemaInfo members for meta-type 'command'. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{arg-type: string} |
| the name of the object type that provides the command's |
| parameters. |
| @item @code{ret-type: string} |
| the name of the command's result type. |
| @item @code{allow-oob: boolean} |
| whether the command allows out-of-band execution. |
| (Since: 2.12) |
| @end table |
| |
| @b{TODO:} |
| @code{success-response} (currently irrelevant, because it's QGA, not QMP) |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SchemaInfoEvent |
| |
| Additional SchemaInfo members for meta-type 'event'. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{arg-type: string} |
| the name of the object type that provides the event's |
| parameters. |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| @section Miscellanea |
| |
| |
| @deftypefn Command {} qmp_capabilities |
| |
| Enable QMP capabilities. |
| |
| Arguments: |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{enable: array of QMPCapability} (optional) |
| An optional list of QMPCapability values to enable. The |
| client must not enable any capability that is not |
| mentioned in the QMP greeting message. If the field is not |
| provided, it means no QMP capabilities will be enabled. |
| (since 2.12) |
| @end table |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "qmp_capabilities", |
| "arguments": @{ "enable": [ "oob" ] @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @b{Notes:} |
| This command is valid exactly when first connecting: it must be |
| issued before any other command will be accepted, and will fail once the |
| monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt) |
| |
| The QMP client needs to explicitly enable QMP capabilities, otherwise |
| all the QMP capabilities will be turned off by default. |
| |
| @b{Since:} |
| 0.13 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} QMPCapability |
| |
| Enumeration of capabilities to be advertised during initial client |
| connection, used for agreeing on particular QMP extension behaviors. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{oob} |
| QMP ability to support Out-Of-Band requests. |
| (Please refer to qmp-spec.txt for more information on OOB) |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} VersionTriple |
| |
| A three-part version number. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{major: int} |
| The major version number. |
| @item @code{minor: int} |
| The minor version number. |
| @item @code{micro: int} |
| The micro version number. |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} VersionInfo |
| |
| A description of QEMU's version. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{qemu: VersionTriple} |
| The version of QEMU. By current convention, a micro |
| version of 50 signifies a development branch. A micro version |
| greater than or equal to 90 signifies a release candidate for |
| the next minor version. A micro version of less than 50 |
| signifies a stable release. |
| @item @code{package: string} |
| QEMU will always set this field to an empty string. Downstream |
| versions of QEMU should set this to a non-empty string. The |
| exact format depends on the downstream however it highly |
| recommended that a unique name is used. |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-version |
| |
| Returns the current version of QEMU. |
| |
| @b{Returns:} |
| A @code{VersionInfo} object describing the current version of QEMU. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-version" @} |
| <- @{ |
| "return":@{ |
| "qemu":@{ |
| "major":0, |
| "minor":11, |
| "micro":5 |
| @}, |
| "package":"" |
| @} |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} CommandInfo |
| |
| Information about a QMP command |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| The command name |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-commands |
| |
| Return a list of supported QMP commands by this server |
| |
| @b{Returns:} |
| A list of @code{CommandInfo} for all supported commands |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-commands" @} |
| <- @{ |
| "return":[ |
| @{ |
| "name":"query-balloon" |
| @}, |
| @{ |
| "name":"system_powerdown" |
| @} |
| ] |
| @} |
| @end example |
| |
| @b{Note:} |
| This example has been shortened as the real response is too long. |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} LostTickPolicy |
| |
| Policy for handling lost ticks in timer devices. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{discard} |
| throw away the missed tick(s) and continue with future injection |
| normally. Guest time may be delayed, unless the OS has explicit |
| handling of lost ticks |
| @item @code{delay} |
| continue to deliver ticks at the normal rate. Guest time will be |
| delayed due to the late tick |
| @item @code{merge} |
| merge the missed tick(s) into one tick and inject. Guest time |
| may be delayed, depending on how the OS reacts to the merging |
| of ticks |
| @item @code{slew} |
| deliver ticks at a higher rate to catch up with the missed tick. The |
| guest time should not be delayed once catchup is complete. |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} add_client |
| |
| Allow client connections for VNC, Spice and socket based |
| character devices to be passed in to QEMU via SCM_RIGHTS. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{protocol: string} |
| protocol name. Valid names are "vnc", "spice" or the |
| name of a character device (eg. from -chardev id=XXXX) |
| @item @code{fdname: string} |
| file descriptor name previously passed via 'getfd' command |
| @item @code{skipauth: boolean} (optional) |
| whether to skip authentication. Only applies |
| to "vnc" and "spice" protocols |
| @item @code{tls: boolean} (optional) |
| whether to perform TLS. Only applies to the "spice" |
| protocol |
| @end table |
| |
| @b{Returns:} |
| nothing on success. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "add_client", "arguments": @{ "protocol": "vnc", |
| "fdname": "myclient" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} NameInfo |
| |
| Guest name information. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} (optional) |
| The name of the guest |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-name |
| |
| Return the name information of a guest. |
| |
| @b{Returns:} |
| @code{NameInfo} of the guest |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-name" @} |
| <- @{ "return": @{ "name": "qemu-name" @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} KvmInfo |
| |
| Information about support for KVM acceleration |
| |
| @b{Members:} |
| @table @asis |
| @item @code{enabled: boolean} |
| true if KVM acceleration is active |
| @item @code{present: boolean} |
| true if KVM acceleration is built into this executable |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-kvm |
| |
| Returns information about KVM acceleration |
| |
| @b{Returns:} |
| @code{KvmInfo} |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-kvm" @} |
| <- @{ "return": @{ "enabled": true, "present": true @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} UuidInfo |
| |
| Guest UUID information (Universally Unique Identifier). |
| |
| @b{Members:} |
| @table @asis |
| @item @code{UUID: string} |
| the UUID of the guest |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| If no UUID was specified for the guest, a null UUID is returned. |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-uuid |
| |
| Query the guest UUID information. |
| |
| @b{Returns:} |
| The @code{UuidInfo} for the guest |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-uuid" @} |
| <- @{ "return": @{ "UUID": "550e8400-e29b-41d4-a716-446655440000" @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} EventInfo |
| |
| Information about a QMP event |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| The event name |
| @end table |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-events |
| |
| Return a list of supported QMP events by this server |
| |
| @b{Returns:} |
| A list of @code{EventInfo} for all supported events |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-events" @} |
| <- @{ |
| "return": [ |
| @{ |
| "name":"SHUTDOWN" |
| @}, |
| @{ |
| "name":"RESET" |
| @} |
| ] |
| @} |
| @end example |
| |
| @b{Note:} |
| This example has been shortened as the real response is too long. |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} CpuInfoArch |
| |
| An enumeration of cpu types that enable additional information during |
| @code{query-cpus} and @code{query-cpus-fast}. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{s390} |
| since 2.12 |
| @item @code{riscv} |
| since 2.12 |
| @item @code{x86} |
| Not documented |
| @item @code{sparc} |
| Not documented |
| @item @code{ppc} |
| Not documented |
| @item @code{mips} |
| Not documented |
| @item @code{tricore} |
| Not documented |
| @item @code{other} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuInfo |
| |
| Information about a virtual CPU |
| |
| @b{Members:} |
| @table @asis |
| @item @code{CPU: int} |
| the index of the virtual CPU |
| @item @code{current: boolean} |
| this only exists for backwards compatibility and should be ignored |
| @item @code{halted: boolean} |
| true if the virtual CPU is in the halt state. Halt usually refers |
| to a processor specific low power mode. |
| @item @code{qom_path: string} |
| path to the CPU object in the QOM tree (since 2.4) |
| @item @code{thread_id: int} |
| ID of the underlying host thread |
| @item @code{props: CpuInstanceProperties} (optional) |
| properties describing to which node/socket/core/thread |
| virtual CPU belongs to, provided if supported by board (since 2.10) |
| @item @code{arch: CpuInfoArch} |
| architecture of the cpu, which determines which additional fields |
| will be listed (since 2.6) |
| @item The members of @code{CpuInfoX86} when @code{arch} is @t{"x86"} |
| @item The members of @code{CpuInfoSPARC} when @code{arch} is @t{"sparc"} |
| @item The members of @code{CpuInfoPPC} when @code{arch} is @t{"ppc"} |
| @item The members of @code{CpuInfoMIPS} when @code{arch} is @t{"mips"} |
| @item The members of @code{CpuInfoTricore} when @code{arch} is @t{"tricore"} |
| @item The members of @code{CpuInfoS390} when @code{arch} is @t{"s390"} |
| @item The members of @code{CpuInfoRISCV} when @code{arch} is @t{"riscv"} |
| @item The members of @code{CpuInfoOther} when @code{arch} is @t{"other"} |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| @code{halted} is a transient state that changes frequently. By the time the |
| data is sent to the client, the guest may no longer be halted. |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuInfoX86 |
| |
| Additional information about a virtual i386 or x86_64 CPU |
| |
| @b{Members:} |
| @table @asis |
| @item @code{pc: int} |
| the 64-bit instruction pointer |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuInfoSPARC |
| |
| Additional information about a virtual SPARC CPU |
| |
| @b{Members:} |
| @table @asis |
| @item @code{pc: int} |
| the PC component of the instruction pointer |
| @item @code{npc: int} |
| the NPC component of the instruction pointer |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuInfoPPC |
| |
| Additional information about a virtual PPC CPU |
| |
| @b{Members:} |
| @table @asis |
| @item @code{nip: int} |
| the instruction pointer |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuInfoMIPS |
| |
| Additional information about a virtual MIPS CPU |
| |
| @b{Members:} |
| @table @asis |
| @item @code{PC: int} |
| the instruction pointer |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuInfoTricore |
| |
| Additional information about a virtual Tricore CPU |
| |
| @b{Members:} |
| @table @asis |
| @item @code{PC: int} |
| the instruction pointer |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuInfoRISCV |
| |
| Additional information about a virtual RISCV CPU |
| |
| @b{Members:} |
| @table @asis |
| @item @code{pc: int} |
| the instruction pointer |
| @end table |
| Since 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuInfoOther |
| |
| No additional information is available about the virtual CPU |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} CpuS390State |
| |
| An enumeration of cpu states that can be assumed by a virtual |
| S390 CPU |
| |
| @b{Values:} |
| @table @asis |
| @item @code{uninitialized} |
| Not documented |
| @item @code{stopped} |
| Not documented |
| @item @code{check-stop} |
| Not documented |
| @item @code{operating} |
| Not documented |
| @item @code{load} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuInfoS390 |
| |
| Additional information about a virtual S390 CPU |
| |
| @b{Members:} |
| @table @asis |
| @item @code{cpu-state: CpuS390State} |
| the virtual CPU's state |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-cpus |
| |
| Returns a list of information about each virtual CPU. |
| |
| This command causes vCPU threads to exit to userspace, which causes |
| a small interruption to guest CPU execution. This will have a negative |
| impact on realtime guests and other latency sensitive guest workloads. |
| It is recommended to use @code{query-cpus-fast} instead of this command to |
| avoid the vCPU interruption. |
| |
| @b{Returns:} |
| a list of @code{CpuInfo} for each virtual CPU |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-cpus" @} |
| <- @{ "return": [ |
| @{ |
| "CPU":0, |
| "current":true, |
| "halted":false, |
| "qom_path":"/machine/unattached/device[0]", |
| "arch":"x86", |
| "pc":3227107138, |
| "thread_id":3134 |
| @}, |
| @{ |
| "CPU":1, |
| "current":false, |
| "halted":true, |
| "qom_path":"/machine/unattached/device[2]", |
| "arch":"x86", |
| "pc":7108165, |
| "thread_id":3135 |
| @} |
| ] |
| @} |
| @end example |
| |
| @b{Notes:} |
| This interface is deprecated (since 2.12.0), and it is strongly |
| recommended that you avoid using it. Use @code{query-cpus-fast} to |
| obtain information about virtual CPUs. |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} CpuInfoFast |
| |
| Information about a virtual CPU |
| |
| @b{Members:} |
| @table @asis |
| @item @code{cpu-index: int} |
| index of the virtual CPU |
| @item @code{qom-path: string} |
| path to the CPU object in the QOM tree |
| @item @code{thread-id: int} |
| ID of the underlying host thread |
| @item @code{props: CpuInstanceProperties} (optional) |
| properties describing to which node/socket/core/thread |
| virtual CPU belongs to, provided if supported by board |
| @item @code{arch: CpuInfoArch} |
| architecture of the cpu, which determines which additional fields |
| will be listed |
| @item The members of @code{CpuInfoOther} when @code{arch} is @t{"x86"} |
| @item The members of @code{CpuInfoOther} when @code{arch} is @t{"sparc"} |
| @item The members of @code{CpuInfoOther} when @code{arch} is @t{"ppc"} |
| @item The members of @code{CpuInfoOther} when @code{arch} is @t{"mips"} |
| @item The members of @code{CpuInfoOther} when @code{arch} is @t{"tricore"} |
| @item The members of @code{CpuInfoS390} when @code{arch} is @t{"s390"} |
| @item The members of @code{CpuInfoRISCV} when @code{arch} is @t{"riscv"} |
| @item The members of @code{CpuInfoOther} when @code{arch} is @t{"other"} |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-cpus-fast |
| |
| Returns information about all virtual CPUs. This command does not |
| incur a performance penalty and should be used in production |
| instead of query-cpus. |
| |
| @b{Returns:} |
| list of @code{CpuInfoFast} |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-cpus-fast" @} |
| <- @{ "return": [ |
| @{ |
| "thread-id": 25627, |
| "props": @{ |
| "core-id": 0, |
| "thread-id": 0, |
| "socket-id": 0 |
| @}, |
| "qom-path": "/machine/unattached/device[0]", |
| "arch":"x86", |
| "cpu-index": 0 |
| @}, |
| @{ |
| "thread-id": 25628, |
| "props": @{ |
| "core-id": 0, |
| "thread-id": 0, |
| "socket-id": 1 |
| @}, |
| "qom-path": "/machine/unattached/device[2]", |
| "arch":"x86", |
| "cpu-index": 1 |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} IOThreadInfo |
| |
| Information about an iothread |
| |
| @b{Members:} |
| @table @asis |
| @item @code{id: string} |
| the identifier of the iothread |
| @item @code{thread-id: int} |
| ID of the underlying host thread |
| @item @code{poll-max-ns: int} |
| maximum polling time in ns, 0 means polling is disabled |
| (since 2.9) |
| @item @code{poll-grow: int} |
| how many ns will be added to polling time, 0 means that it's not |
| configured (since 2.9) |
| @item @code{poll-shrink: int} |
| how many ns will be removed from polling time, 0 means that |
| it's not configured (since 2.9) |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-iothreads |
| |
| Returns a list of information about each iothread. |
| |
| @b{Note:} |
| this list excludes the QEMU main loop thread, which is not declared |
| using the -object iothread command-line option. It is always the main thread |
| of the process. |
| |
| @b{Returns:} |
| a list of @code{IOThreadInfo} for each iothread |
| |
| @b{Since:} |
| 2.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-iothreads" @} |
| <- @{ "return": [ |
| @{ |
| "id":"iothread0", |
| "thread-id":3134 |
| @}, |
| @{ |
| "id":"iothread1", |
| "thread-id":3135 |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} BalloonInfo |
| |
| Information about the guest balloon device. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{actual: int} |
| the number of bytes the balloon currently contains |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-balloon |
| |
| Return information about the balloon device. |
| |
| @b{Returns:} |
| @code{BalloonInfo} on success |
| |
| If the balloon driver is enabled but not functional because the KVM |
| kernel module cannot support it, KvmMissingCap |
| |
| If no balloon device is present, DeviceNotActive |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-balloon" @} |
| <- @{ "return": @{ |
| "actual": 1073741824, |
| @} |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} BALLOON_CHANGE |
| |
| Emitted when the guest changes the actual BALLOON level. This value is |
| equivalent to the @code{actual} field return by the 'query-balloon' command |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{actual: int} |
| actual level of the guest memory balloon in bytes |
| @end table |
| |
| @b{Note:} |
| this event is rate-limited. |
| |
| @b{Since:} |
| 1.2 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "BALLOON_CHANGE", |
| "data": @{ "actual": 944766976 @}, |
| "timestamp": @{ "seconds": 1267020223, "microseconds": 435656 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} PciMemoryRange |
| |
| A PCI device memory region |
| |
| @b{Members:} |
| @table @asis |
| @item @code{base: int} |
| the starting address (guest physical) |
| @item @code{limit: int} |
| the ending address (guest physical) |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} PciMemoryRegion |
| |
| Information about a PCI device I/O region. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{bar: int} |
| the index of the Base Address Register for this region |
| @item @code{type: string} |
| 'io' if the region is a PIO region |
| 'memory' if the region is a MMIO region |
| @item @code{size: int} |
| memory size |
| @item @code{prefetch: boolean} (optional) |
| if @code{type} is 'memory', true if the memory is prefetchable |
| @item @code{mem_type_64: boolean} (optional) |
| if @code{type} is 'memory', true if the BAR is 64-bit |
| @item @code{address: int} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} PciBusInfo |
| |
| Information about a bus of a PCI Bridge device |
| |
| @b{Members:} |
| @table @asis |
| @item @code{number: int} |
| primary bus interface number. This should be the number of the |
| bus the device resides on. |
| @item @code{secondary: int} |
| secondary bus interface number. This is the number of the |
| main bus for the bridge |
| @item @code{subordinate: int} |
| This is the highest number bus that resides below the |
| bridge. |
| @item @code{io_range: PciMemoryRange} |
| The PIO range for all devices on this bridge |
| @item @code{memory_range: PciMemoryRange} |
| The MMIO range for all devices on this bridge |
| @item @code{prefetchable_range: PciMemoryRange} |
| The range of prefetchable MMIO for all devices on |
| this bridge |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} PciBridgeInfo |
| |
| Information about a PCI Bridge device |
| |
| @b{Members:} |
| @table @asis |
| @item @code{bus: PciBusInfo} |
| information about the bus the device resides on |
| @item @code{devices: array of PciDeviceInfo} (optional) |
| a list of @code{PciDeviceInfo} for each device on this bridge |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} PciDeviceClass |
| |
| Information about the Class of a PCI device |
| |
| @b{Members:} |
| @table @asis |
| @item @code{desc: string} (optional) |
| a string description of the device's class |
| @item @code{class: int} |
| the class code of the device |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} PciDeviceId |
| |
| Information about the Id of a PCI device |
| |
| @b{Members:} |
| @table @asis |
| @item @code{device: int} |
| the PCI device id |
| @item @code{vendor: int} |
| the PCI vendor id |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} PciDeviceInfo |
| |
| Information about a PCI device |
| |
| @b{Members:} |
| @table @asis |
| @item @code{bus: int} |
| the bus number of the device |
| @item @code{slot: int} |
| the slot the device is located in |
| @item @code{function: int} |
| the function of the slot used by the device |
| @item @code{class_info: PciDeviceClass} |
| the class of the device |
| @item @code{id: PciDeviceId} |
| the PCI device id |
| @item @code{irq: int} (optional) |
| if an IRQ is assigned to the device, the IRQ number |
| @item @code{qdev_id: string} |
| the device name of the PCI device |
| @item @code{pci_bridge: PciBridgeInfo} (optional) |
| if the device is a PCI bridge, the bridge information |
| @item @code{regions: array of PciMemoryRegion} |
| a list of the PCI I/O regions associated with the device |
| @end table |
| |
| @b{Notes:} |
| the contents of @code{class_info}.desc are not stable and should only be |
| treated as informational. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} PciInfo |
| |
| Information about a PCI bus |
| |
| @b{Members:} |
| @table @asis |
| @item @code{bus: int} |
| the bus index |
| @item @code{devices: array of PciDeviceInfo} |
| a list of devices on this bus |
| @end table |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-pci |
| |
| Return information about the PCI bus topology of the guest. |
| |
| @b{Returns:} |
| a list of @code{PciInfo} for each PCI bus. Each bus is |
| represented by a json-object, which has a key with a json-array of |
| all PCI devices attached to it. Each device is represented by a |
| json-object. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-pci" @} |
| <- @{ "return": [ |
| @{ |
| "bus": 0, |
| "devices": [ |
| @{ |
| "bus": 0, |
| "qdev_id": "", |
| "slot": 0, |
| "class_info": @{ |
| "class": 1536, |
| "desc": "Host bridge" |
| @}, |
| "id": @{ |
| "device": 32902, |
| "vendor": 4663 |
| @}, |
| "function": 0, |
| "regions": [ |
| ] |
| @}, |
| @{ |
| "bus": 0, |
| "qdev_id": "", |
| "slot": 1, |
| "class_info": @{ |
| "class": 1537, |
| "desc": "ISA bridge" |
| @}, |
| "id": @{ |
| "device": 32902, |
| "vendor": 28672 |
| @}, |
| "function": 0, |
| "regions": [ |
| ] |
| @}, |
| @{ |
| "bus": 0, |
| "qdev_id": "", |
| "slot": 1, |
| "class_info": @{ |
| "class": 257, |
| "desc": "IDE controller" |
| @}, |
| "id": @{ |
| "device": 32902, |
| "vendor": 28688 |
| @}, |
| "function": 1, |
| "regions": [ |
| @{ |
| "bar": 4, |
| "size": 16, |
| "address": 49152, |
| "type": "io" |
| @} |
| ] |
| @}, |
| @{ |
| "bus": 0, |
| "qdev_id": "", |
| "slot": 2, |
| "class_info": @{ |
| "class": 768, |
| "desc": "VGA controller" |
| @}, |
| "id": @{ |
| "device": 4115, |
| "vendor": 184 |
| @}, |
| "function": 0, |
| "regions": [ |
| @{ |
| "prefetch": true, |
| "mem_type_64": false, |
| "bar": 0, |
| "size": 33554432, |
| "address": 4026531840, |
| "type": "memory" |
| @}, |
| @{ |
| "prefetch": false, |
| "mem_type_64": false, |
| "bar": 1, |
| "size": 4096, |
| "address": 4060086272, |
| "type": "memory" |
| @}, |
| @{ |
| "prefetch": false, |
| "mem_type_64": false, |
| "bar": 6, |
| "size": 65536, |
| "address": -1, |
| "type": "memory" |
| @} |
| ] |
| @}, |
| @{ |
| "bus": 0, |
| "qdev_id": "", |
| "irq": 11, |
| "slot": 4, |
| "class_info": @{ |
| "class": 1280, |
| "desc": "RAM controller" |
| @}, |
| "id": @{ |
| "device": 6900, |
| "vendor": 4098 |
| @}, |
| "function": 0, |
| "regions": [ |
| @{ |
| "bar": 0, |
| "size": 32, |
| "address": 49280, |
| "type": "io" |
| @} |
| ] |
| @} |
| ] |
| @} |
| ] |
| @} |
| @end example |
| |
| @b{Note:} |
| This example has been shortened as the real response is too long. |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} quit |
| |
| This command will cause the QEMU process to exit gracefully. While every |
| attempt is made to send the QMP response before terminating, this is not |
| guaranteed. When using this interface, a premature EOF would not be |
| unexpected. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "quit" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} stop |
| |
| Stop all guest VCPU execution. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| This function will succeed even if the guest is already in the stopped |
| state. In "inmigrate" state, it will ensure that the guest |
| remains paused once migration finishes, as if the -S option was |
| passed on the command line. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "stop" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} system_reset |
| |
| Performs a hard reset of a guest. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "system_reset" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} system_powerdown |
| |
| Requests that a guest perform a powerdown operation. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| A guest may or may not respond to this command. This command |
| returning does not indicate that a guest has accepted the request or |
| that it has shut down. Many guests will respond to this command by |
| prompting the user in some way. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "system_powerdown" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} cpu-add |
| |
| Adds CPU with specified ID |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: int} |
| ID of CPU to be created, valid values [0..max_cpus) |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 1.5 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "cpu-add", "arguments": @{ "id": 2 @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} memsave |
| |
| Save a portion of guest memory to a file. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{val: int} |
| the virtual address of the guest to start from |
| @item @code{size: int} |
| the size of memory region to save |
| @item @code{filename: string} |
| the file to save the memory to as binary data |
| @item @code{cpu-index: int} (optional) |
| the index of the virtual CPU to use for translating the |
| virtual address (defaults to CPU 0) |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| Errors were not reliably returned until 1.1 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "memsave", |
| "arguments": @{ "val": 10, |
| "size": 100, |
| "filename": "/tmp/virtual-mem-dump" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} pmemsave |
| |
| Save a portion of guest physical memory to a file. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{val: int} |
| the physical address of the guest to start from |
| @item @code{size: int} |
| the size of memory region to save |
| @item @code{filename: string} |
| the file to save the memory to as binary data |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| Errors were not reliably returned until 1.1 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "pmemsave", |
| "arguments": @{ "val": 10, |
| "size": 100, |
| "filename": "/tmp/physical-mem-dump" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} cont |
| |
| Resume guest VCPU execution. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Returns:} |
| If successful, nothing |
| |
| @b{Notes:} |
| This command will succeed if the guest is currently running. It |
| will also succeed if the guest is in the "inmigrate" state; in |
| this case, the effect of the command is to make sure the guest |
| starts once migration finishes, removing the effect of the -S |
| command line option if it was passed. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "cont" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} system_wakeup |
| |
| Wakeup guest from suspend. Does nothing in case the guest isn't suspended. |
| |
| @b{Since:} |
| 1.1 |
| |
| @b{Returns:} |
| nothing. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "system_wakeup" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} inject-nmi |
| |
| Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64). |
| The command fails when the guest doesn't support injecting. |
| |
| @b{Returns:} |
| If successful, nothing |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Note:} |
| prior to 2.1, this command was only supported for x86 and s390 VMs |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "inject-nmi" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} balloon |
| |
| Request the balloon driver to change its balloon size. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{value: int} |
| the target size of the balloon in bytes |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If the balloon driver is enabled but not functional because the KVM |
| kernel module cannot support it, KvmMissingCap |
| If no balloon device is present, DeviceNotActive |
| |
| @b{Notes:} |
| This command just issues a request to the guest. When it returns, |
| the balloon size may not have changed. A guest can change the balloon |
| size independent of this command. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "balloon", "arguments": @{ "value": 536870912 @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} human-monitor-command |
| |
| Execute a command on the human monitor and return the output. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{command-line: string} |
| the command to execute in the human monitor |
| @item @code{cpu-index: int} (optional) |
| The CPU to use for commands that require an implicit CPU |
| @end table |
| |
| @b{Returns:} |
| the output of the command as a string |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| This command only exists as a stop-gap. Its use is highly |
| discouraged. The semantics of this command are not |
| guaranteed: this means that command names, arguments and |
| responses can change or be removed at ANY time. Applications |
| that rely on long term stability guarantees should NOT |
| use this command. |
| |
| Known limitations: |
| |
| @itemize @bullet |
| @item |
| This command is stateless, this means that commands that depend |
| on state information (such as getfd) might not work |
| |
| @item |
| Commands that prompt the user for data don't currently work |
| @end itemize |
| |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "human-monitor-command", |
| "arguments": @{ "command-line": "info kvm" @} @} |
| <- @{ "return": "kvm support: enabled\r\n" @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} ObjectPropertyInfo |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| the name of the property |
| @item @code{type: string} |
| the type of the property. This will typically come in one of four |
| forms: |
| |
| 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'. |
| These types are mapped to the appropriate JSON type. |
| |
| 2) A child type in the form 'child<subtype>' where subtype is a qdev |
| device type name. Child properties create the composition tree. |
| |
| 3) A link type in the form 'link<subtype>' where subtype is a qdev |
| device type name. Link properties form the device model graph. |
| @item @code{description: string} (optional) |
| if specified, the description of the property. |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} qom-list |
| |
| This command will list any properties of a object given a path in the object |
| model. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{path: string} |
| the path within the object model. See @code{qom-get} for a description of |
| this parameter. |
| @end table |
| |
| @b{Returns:} |
| a list of @code{ObjectPropertyInfo} that describe the properties of the |
| object. |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} qom-get |
| |
| This command will get a property from a object model path and return the |
| value. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{path: string} |
| The path within the object model. There are two forms of supported |
| paths--absolute and partial paths. |
| |
| Absolute paths are derived from the root object and can follow child<> |
| or link<> properties. Since they can follow link<> properties, they |
| can be arbitrarily long. Absolute paths look like absolute filenames |
| and are prefixed with a leading slash. |
| |
| Partial paths look like relative filenames. They do not begin |
| with a prefix. The matching rules for partial paths are subtle but |
| designed to make specifying objects easy. At each level of the |
| composition tree, the partial path is matched as an absolute path. |
| The first match is not returned. At least two matches are searched |
| for. A successful result is only returned if only one match is |
| found. If more than one match is found, a flag is return to |
| indicate that the match was ambiguous. |
| @item @code{property: string} |
| The property name to read |
| @end table |
| |
| @b{Returns:} |
| The property value. The type depends on the property |
| type. child<> and link<> properties are returned as #str |
| pathnames. All integer property types (u8, u16, etc) are |
| returned as #int. |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} qom-set |
| |
| This command will set a property from a object model path. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{path: string} |
| see @code{qom-get} for a description of this parameter |
| @item @code{property: string} |
| the property name to set |
| @item @code{value: value} |
| a value who's type is appropriate for the property type. See @code{qom-get} |
| for a description of type mapping. |
| @end table |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} change |
| |
| This command is multiple commands multiplexed together. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| This is normally the name of a block device but it may also be 'vnc'. |
| when it's 'vnc', then sub command depends on @code{target} |
| @item @code{target: string} |
| If @code{device} is a block device, then this is the new filename. |
| If @code{device} is 'vnc', then if the value 'password' selects the vnc |
| change password command. Otherwise, this specifies a new server URI |
| address to listen to for VNC connections. |
| @item @code{arg: string} (optional) |
| If @code{device} is a block device, then this is an optional format to open |
| the device with. |
| If @code{device} is 'vnc' and @code{target} is 'password', this is the new VNC |
| password to set. See change-vnc-password for additional notes. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success. |
| If @code{device} is not a valid block device, DeviceNotFound |
| |
| @b{Notes:} |
| This interface is deprecated, and it is strongly recommended that you |
| avoid using it. For changing block devices, use |
| blockdev-change-medium; for changing VNC parameters, use |
| change-vnc-password. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| 1. Change a removable medium |
| |
| -> @{ "execute": "change", |
| "arguments": @{ "device": "ide1-cd0", |
| "target": "/srv/images/Fedora-12-x86_64-DVD.iso" @} @} |
| <- @{ "return": @{@} @} |
| |
| 2. Change VNC password |
| |
| -> @{ "execute": "change", |
| "arguments": @{ "device": "vnc", "target": "password", |
| "arg": "foobar1" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} ObjectTypeInfo |
| |
| This structure describes a search result from @code{qom-list-types} |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| the type name found in the search |
| @item @code{abstract: boolean} (optional) |
| the type is abstract and can't be directly instantiated. |
| Omitted if false. (since 2.10) |
| @item @code{parent: string} (optional) |
| Name of parent type, if any (since 2.10) |
| @end table |
| |
| @b{Since:} |
| 1.1 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} qom-list-types |
| |
| This command will return a list of types given search parameters |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{implements: string} (optional) |
| if specified, only return types that implement this type name |
| @item @code{abstract: boolean} (optional) |
| if true, include abstract types in the results |
| @end table |
| |
| @b{Returns:} |
| a list of @code{ObjectTypeInfo} or an empty list if no results are found |
| |
| @b{Since:} |
| 1.1 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} device-list-properties |
| |
| List properties associated with a device. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{typename: string} |
| the type name of a device |
| @end table |
| |
| @b{Returns:} |
| a list of ObjectPropertyInfo describing a devices properties |
| |
| @b{Since:} |
| 1.2 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} qom-list-properties |
| |
| List properties associated with a QOM object. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{typename: string} |
| the type name of an object |
| @end table |
| |
| @b{Returns:} |
| a list of ObjectPropertyInfo describing object properties |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} xen-set-global-dirty-log |
| |
| Enable or disable the global dirty log mode. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{enable: boolean} |
| true to enable, false to disable. |
| @end table |
| |
| @b{Returns:} |
| nothing |
| |
| @b{Since:} |
| 1.3 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "xen-set-global-dirty-log", |
| "arguments": @{ "enable": true @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} device_add |
| |
| |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{driver: string} |
| the name of the new device's driver |
| @item @code{bus: string} (optional) |
| the device's parent bus (device tree path) |
| @item @code{id: string} (optional) |
| the device's ID, must be unique |
| @end table |
| Additional arguments depend on the type. |
| |
| Add a device. |
| |
| @b{Notes:} |
| @enumerate |
| @item |
| For detailed information about this command, please refer to the |
| 'docs/qdev-device-use.txt' file. |
| |
| @item |
| It's possible to list device properties by running QEMU with the |
| "-device DEVICE,help" command-line argument, where DEVICE is the |
| device's name |
| @end enumerate |
| |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "device_add", |
| "arguments": @{ "driver": "e1000", "id": "net1", |
| "bus": "pci.0", |
| "mac": "52:54:00:12:34:56" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @b{TODO:} |
| This command effectively bypasses QAPI completely due to its |
| "additional arguments" business. It shouldn't have been added to |
| the schema in this form. It should be qapified properly, or |
| replaced by a properly qapified command. |
| |
| @b{Since:} |
| 0.13 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} device_del |
| |
| Remove a device from a guest |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| the device's ID or QOM path |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If @code{id} is not a valid device, DeviceNotFound |
| |
| @b{Notes:} |
| When this command completes, the device may not be removed from the |
| guest. Hot removal is an operation that requires guest cooperation. |
| This command merely requests that the guest begin the hot removal |
| process. Completion of the device removal process is signaled with a |
| DEVICE_DELETED event. Guest reset will automatically complete removal |
| for all devices. |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "device_del", |
| "arguments": @{ "id": "net1" @} @} |
| <- @{ "return": @{@} @} |
| |
| -> @{ "execute": "device_del", |
| "arguments": @{ "id": "/machine/peripheral-anon/device[0]" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} DEVICE_DELETED |
| |
| Emitted whenever the device removal completion is acknowledged by the guest. |
| At this point, it's safe to reuse the specified device ID. Device removal can |
| be initiated by the guest or by HMP/QMP commands. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} (optional) |
| device name |
| @item @code{path: string} |
| device path |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "DEVICE_DELETED", |
| "data": @{ "device": "virtio-net-pci-0", |
| "path": "/machine/peripheral/virtio-net-pci-0" @}, |
| "timestamp": @{ "seconds": 1265044230, "microseconds": 450486 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} DumpGuestMemoryFormat |
| |
| An enumeration of guest-memory-dump's format. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{elf} |
| elf format |
| @item @code{kdump-zlib} |
| kdump-compressed format with zlib-compressed |
| @item @code{kdump-lzo} |
| kdump-compressed format with lzo-compressed |
| @item @code{kdump-snappy} |
| kdump-compressed format with snappy-compressed |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} dump-guest-memory |
| |
| Dump guest's memory to vmcore. It is a synchronous operation that can take |
| very long depending on the amount of guest memory. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{paging: boolean} |
| if true, do paging to get guest's memory mapping. This allows |
| using gdb to process the core file. |
| |
| IMPORTANT: this option can make QEMU allocate several gigabytes |
| of RAM. This can happen for a large guest, or a |
| malicious guest pretending to be large. |
| |
| Also, paging=true has the following limitations: |
| |
| @enumerate |
| @item |
| The guest may be in a catastrophic state or can have corrupted |
| memory, which cannot be trusted |
| @item |
| The guest can be in real-mode even if paging is enabled. For |
| example, the guest uses ACPI to sleep, and ACPI sleep state |
| goes in real-mode |
| @item |
| Currently only supported on i386 and x86_64. |
| @end enumerate |
| |
| @item @code{protocol: string} |
| the filename or file descriptor of the vmcore. The supported |
| protocols are: |
| |
| @enumerate |
| @item |
| file: the protocol starts with "file:", and the following |
| string is the file's path. |
| @item |
| fd: the protocol starts with "fd:", and the following string |
| is the fd's name. |
| @end enumerate |
| |
| @item @code{detach: boolean} (optional) |
| if true, QMP will return immediately rather than |
| waiting for the dump to finish. The user can track progress |
| using "query-dump". (since 2.6). |
| @item @code{begin: int} (optional) |
| if specified, the starting physical address. |
| @item @code{length: int} (optional) |
| if specified, the memory size, in bytes. If you don't |
| want to dump all guest's memory, please specify the start @code{begin} |
| and @code{length} |
| @item @code{format: DumpGuestMemoryFormat} (optional) |
| if specified, the format of guest memory dump. But non-elf |
| format is conflict with paging and filter, ie. @code{paging}, @code{begin} and |
| @code{length} is not allowed to be specified with non-elf @code{format} at the |
| same time (since 2.0) |
| @end table |
| |
| @b{Note:} |
| All boolean arguments default to false |
| |
| @b{Returns:} |
| nothing on success |
| |
| @b{Since:} |
| 1.2 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "dump-guest-memory", |
| "arguments": @{ "protocol": "fd:dump" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} DumpStatus |
| |
| Describe the status of a long-running background guest memory dump. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{none} |
| no dump-guest-memory has started yet. |
| @item @code{active} |
| there is one dump running in background. |
| @item @code{completed} |
| the last dump has finished successfully. |
| @item @code{failed} |
| the last dump has failed. |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} DumpQueryResult |
| |
| The result format for 'query-dump'. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{status: DumpStatus} |
| enum of @code{DumpStatus}, which shows current dump status |
| @item @code{completed: int} |
| bytes written in latest dump (uncompressed) |
| @item @code{total: int} |
| total bytes to be written in latest dump (uncompressed) |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-dump |
| |
| Query latest dump status. |
| |
| @b{Returns:} |
| A @code{DumpStatus} object showing the dump status. |
| |
| @b{Since:} |
| 2.6 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-dump" @} |
| <- @{ "return": @{ "status": "active", "completed": 1024000, |
| "total": 2048000 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} DUMP_COMPLETED |
| |
| Emitted when background dump has completed |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{result: DumpQueryResult} |
| final dump status |
| @item @code{error: string} (optional) |
| human-readable error string that provides |
| hint on why dump failed. Only presents on failure. The |
| user should not try to interpret the error string. |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @b{Example:} |
| @example |
| @{ "event": "DUMP_COMPLETED", |
| "data": @{"result": @{"total": 1090650112, "status": "completed", |
| "completed": 1090650112@} @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} DumpGuestMemoryCapability |
| |
| A list of the available formats for dump-guest-memory |
| |
| @b{Members:} |
| @table @asis |
| @item @code{formats: array of DumpGuestMemoryFormat} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-dump-guest-memory-capability |
| |
| Returns the available formats for dump-guest-memory |
| |
| @b{Returns:} |
| A @code{DumpGuestMemoryCapability} object listing available formats for |
| dump-guest-memory |
| |
| @b{Since:} |
| 2.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-dump-guest-memory-capability" @} |
| <- @{ "return": @{ "formats": |
| ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} dump-skeys |
| |
| Dump guest's storage keys |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{filename: string} |
| the path to the file to dump to |
| @end table |
| This command is only supported on s390 architecture. |
| |
| @b{Since:} |
| 2.5 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "dump-skeys", |
| "arguments": @{ "filename": "/tmp/skeys" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} object-add |
| |
| Create a QOM object. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{qom-type: string} |
| the class name for the object to be created |
| @item @code{id: string} |
| the name of the new object |
| @item @code{props: value} (optional) |
| a dictionary of properties to be passed to the backend |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| Error if @code{qom-type} is not a valid class name |
| |
| @b{Since:} |
| 2.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "object-add", |
| "arguments": @{ "qom-type": "rng-random", "id": "rng1", |
| "props": @{ "filename": "/dev/hwrng" @} @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} object-del |
| |
| Remove a QOM object. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: string} |
| the name of the QOM object to remove |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| Error if @code{id} is not a valid id for a QOM object |
| |
| @b{Since:} |
| 2.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "object-del", "arguments": @{ "id": "rng1" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} getfd |
| |
| Receive a file descriptor via SCM rights and assign it a name |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{fdname: string} |
| file descriptor name |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Notes:} |
| If @code{fdname} already exists, the file descriptor assigned to |
| it will be closed and replaced by the received file |
| descriptor. |
| |
| The 'closefd' command can be used to explicitly close the |
| file descriptor when it is no longer needed. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "getfd", "arguments": @{ "fdname": "fd1" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} closefd |
| |
| Close a file descriptor previously passed via SCM rights |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{fdname: string} |
| file descriptor name |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| |
| @b{Since:} |
| 0.14.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "closefd", "arguments": @{ "fdname": "fd1" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} MachineInfo |
| |
| Information describing a machine. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| the name of the machine |
| @item @code{alias: string} (optional) |
| an alias for the machine name |
| @item @code{is-default: boolean} (optional) |
| whether the machine is default |
| @item @code{cpu-max: int} |
| maximum number of CPUs supported by the machine type |
| (since 1.5.0) |
| @item @code{hotpluggable-cpus: boolean} |
| cpu hotplug via -device is supported (since 2.7.0) |
| @end table |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-machines |
| |
| Return a list of supported machines |
| |
| @b{Returns:} |
| a list of MachineInfo |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} CpuDefinitionInfo |
| |
| Virtual CPU definition. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| the name of the CPU definition |
| @item @code{migration-safe: boolean} (optional) |
| whether a CPU definition can be safely used for |
| migration in combination with a QEMU compatibility machine |
| when migrating between different QMU versions and between |
| hosts with different sets of (hardware or software) |
| capabilities. If not provided, information is not available |
| and callers should not assume the CPU definition to be |
| migration-safe. (since 2.8) |
| @item @code{static: boolean} |
| whether a CPU definition is static and will not change depending on |
| QEMU version, machine type, machine options and accelerator options. |
| A static model is always migration-safe. (since 2.8) |
| @item @code{unavailable-features: array of string} (optional) |
| List of properties that prevent |
| the CPU model from running in the current |
| host. (since 2.8) |
| @item @code{typename: string} |
| Type name that can be used as argument to @code{device-list-properties}, |
| to introspect properties configurable using -cpu or -global. |
| (since 2.9) |
| @end table |
| @code{unavailable-features} is a list of QOM property names that |
| represent CPU model attributes that prevent the CPU from running. |
| If the QOM property is read-only, that means there's no known |
| way to make the CPU model run in the current host. Implementations |
| that choose not to provide specific information return the |
| property name "type". |
| If the property is read-write, it means that it MAY be possible |
| to run the CPU model in the current host if that property is |
| changed. Management software can use it as hints to suggest or |
| choose an alternative for the user, or just to generate meaningful |
| error messages explaining why the CPU model can't be used. |
| If @code{unavailable-features} is an empty list, the CPU model is |
| runnable using the current host and machine-type. |
| If @code{unavailable-features} is not present, runnability |
| information for the CPU is not available. |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} MemoryInfo |
| |
| Actual memory information in bytes. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{base-memory: int} |
| size of "base" memory specified with command line |
| option -m. |
| @item @code{plugged-memory: int} (optional) |
| size of memory that can be hot-unplugged. This field |
| is omitted if target doesn't support memory hotplug |
| (i.e. CONFIG_MEM_HOTPLUG not defined on build time). |
| @end table |
| |
| @b{Since:} |
| 2.11.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-memory-size-summary |
| |
| Return the amount of initially allocated and present hotpluggable (if |
| enabled) memory in bytes. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-memory-size-summary" @} |
| <- @{ "return": @{ "base-memory": 4294967296, "plugged-memory": 0 @} @} |
| @end example |
| |
| @b{Since:} |
| 2.11.0 |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} query-cpu-definitions |
| |
| Return a list of supported virtual CPU definitions |
| |
| @b{Returns:} |
| a list of CpuDefInfo |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} CpuModelInfo |
| |
| Virtual CPU model. |
| |
| A CPU model consists of the name of a CPU definition, to which |
| delta changes are applied (e.g. features added/removed). Most magic values |
| that an architecture might require should be hidden behind the name. |
| However, if required, architectures can expose relevant properties. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| the name of the CPU definition the model is based on |
| @item @code{props: value} (optional) |
| a dictionary of QOM properties to be applied |
| @end table |
| |
| @b{Since:} |
| 2.8.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} CpuModelExpansionType |
| |
| An enumeration of CPU model expansion types. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{static} |
| Expand to a static CPU model, a combination of a static base |
| model name and property delta changes. As the static base model will |
| never change, the expanded CPU model will be the same, independent of |
| independent of QEMU version, machine type, machine options, and |
| accelerator options. Therefore, the resulting model can be used by |
| tooling without having to specify a compatibility machine - e.g. when |
| displaying the "host" model. static CPU models are migration-safe. |
| @item @code{full} |
| Expand all properties. The produced model is not guaranteed to be |
| migration-safe, but allows tooling to get an insight and work with |
| model details. |
| @end table |
| |
| @b{Note:} |
| When a non-migration-safe CPU model is expanded in static mode, some |
| features enabled by the CPU model may be omitted, because they can't be |
| implemented by a static CPU model definition (e.g. cache info passthrough and |
| PMU passthrough in x86). If you need an accurate representation of the |
| features enabled by a non-migration-safe CPU model, use @code{full}. If you need a |
| static representation that will keep ABI compatibility even when changing QEMU |
| version or machine-type, use @code{static} (but keep in mind that some features may |
| be omitted). |
| |
| @b{Since:} |
| 2.8.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuModelExpansionInfo |
| |
| The result of a cpu model expansion. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{model: CpuModelInfo} |
| the expanded CpuModelInfo. |
| @end table |
| |
| @b{Since:} |
| 2.8.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-cpu-model-expansion |
| |
| Expands a given CPU model (or a combination of CPU model + additional options) |
| to different granularities, allowing tooling to get an understanding what a |
| specific CPU model looks like in QEMU under a certain configuration. |
| |
| This interface can be used to query the "host" CPU model. |
| |
| The data returned by this command may be affected by: |
| |
| @itemize @bullet |
| @item |
| QEMU version: CPU models may look different depending on the QEMU version. |
| (Except for CPU models reported as "static" in query-cpu-definitions.) |
| @item |
| machine-type: CPU model may look different depending on the machine-type. |
| (Except for CPU models reported as "static" in query-cpu-definitions.) |
| @item |
| machine options (including accelerator): in some architectures, CPU models |
| may look different depending on machine and accelerator options. (Except for |
| CPU models reported as "static" in query-cpu-definitions.) |
| @item |
| "-cpu" arguments and global properties: arguments to the -cpu option and |
| global properties may affect expansion of CPU models. Using |
| query-cpu-model-expansion while using these is not advised. |
| |
| @end itemize |
| |
| Some architectures may not support all expansion types. s390x supports |
| "full" and "static". |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{type: CpuModelExpansionType} |
| Not documented |
| @item @code{model: CpuModelInfo} |
| Not documented |
| @end table |
| |
| @b{Returns:} |
| a CpuModelExpansionInfo. Returns an error if expanding CPU models is |
| not supported, if the model cannot be expanded, if the model contains |
| an unknown CPU definition name, unknown properties or properties |
| with a wrong type. Also returns an error if an expansion type is |
| not supported. |
| |
| @b{Since:} |
| 2.8.0 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} CpuModelCompareResult |
| |
| An enumeration of CPU model comparison results. The result is usually |
| calculated using e.g. CPU features or CPU generations. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{incompatible} |
| If model A is incompatible to model B, model A is not |
| guaranteed to run where model B runs and the other way around. |
| @item @code{identical} |
| If model A is identical to model B, model A is guaranteed to run |
| where model B runs and the other way around. |
| @item @code{superset} |
| If model A is a superset of model B, model B is guaranteed to run |
| where model A runs. There are no guarantees about the other way. |
| @item @code{subset} |
| If model A is a subset of model B, model A is guaranteed to run |
| where model B runs. There are no guarantees about the other way. |
| @end table |
| |
| @b{Since:} |
| 2.8.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CpuModelCompareInfo |
| |
| The result of a CPU model comparison. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{result: CpuModelCompareResult} |
| The result of the compare operation. |
| @item @code{responsible-properties: array of string} |
| List of properties that led to the comparison result |
| not being identical. |
| @end table |
| @code{responsible-properties} is a list of QOM property names that led to |
| both CPUs not being detected as identical. For identical models, this |
| list is empty. |
| If a QOM property is read-only, that means there's no known way to make the |
| CPU models identical. If the special property name "type" is included, the |
| models are by definition not identical and cannot be made identical. |
| |
| @b{Since:} |
| 2.8.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-cpu-model-comparison |
| |
| Compares two CPU models, returning how they compare in a specific |
| configuration. The results indicates how both models compare regarding |
| runnability. This result can be used by tooling to make decisions if a |
| certain CPU model will run in a certain configuration or if a compatible |
| CPU model has to be created by baselining. |
| |
| Usually, a CPU model is compared against the maximum possible CPU model |
| of a certain configuration (e.g. the "host" model for KVM). If that CPU |
| model is identical or a subset, it will run in that configuration. |
| |
| The result returned by this command may be affected by: |
| |
| @itemize @bullet |
| @item |
| QEMU version: CPU models may look different depending on the QEMU version. |
| (Except for CPU models reported as "static" in query-cpu-definitions.) |
| @item |
| machine-type: CPU model may look different depending on the machine-type. |
| (Except for CPU models reported as "static" in query-cpu-definitions.) |
| @item |
| machine options (including accelerator): in some architectures, CPU models |
| may look different depending on machine and accelerator options. (Except for |
| CPU models reported as "static" in query-cpu-definitions.) |
| @item |
| "-cpu" arguments and global properties: arguments to the -cpu option and |
| global properties may affect expansion of CPU models. Using |
| query-cpu-model-expansion while using these is not advised. |
| |
| @end itemize |
| |
| Some architectures may not support comparing CPU models. s390x supports |
| comparing CPU models. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{modela: CpuModelInfo} |
| Not documented |
| @item @code{modelb: CpuModelInfo} |
| Not documented |
| @end table |
| |
| @b{Returns:} |
| a CpuModelBaselineInfo. Returns an error if comparing CPU models is |
| not supported, if a model cannot be used, if a model contains |
| an unknown cpu definition name, unknown properties or properties |
| with wrong types. |
| |
| @b{Since:} |
| 2.8.0 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} CpuModelBaselineInfo |
| |
| The result of a CPU model baseline. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{model: CpuModelInfo} |
| the baselined CpuModelInfo. |
| @end table |
| |
| @b{Since:} |
| 2.8.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-cpu-model-baseline |
| |
| Baseline two CPU models, creating a compatible third model. The created |
| model will always be a static, migration-safe CPU model (see "static" |
| CPU model expansion for details). |
| |
| This interface can be used by tooling to create a compatible CPU model out |
| two CPU models. The created CPU model will be identical to or a subset of |
| both CPU models when comparing them. Therefore, the created CPU model is |
| guaranteed to run where the given CPU models run. |
| |
| The result returned by this command may be affected by: |
| |
| @itemize @bullet |
| @item |
| QEMU version: CPU models may look different depending on the QEMU version. |
| (Except for CPU models reported as "static" in query-cpu-definitions.) |
| @item |
| machine-type: CPU model may look different depending on the machine-type. |
| (Except for CPU models reported as "static" in query-cpu-definitions.) |
| @item |
| machine options (including accelerator): in some architectures, CPU models |
| may look different depending on machine and accelerator options. (Except for |
| CPU models reported as "static" in query-cpu-definitions.) |
| @item |
| "-cpu" arguments and global properties: arguments to the -cpu option and |
| global properties may affect expansion of CPU models. Using |
| query-cpu-model-expansion while using these is not advised. |
| |
| @end itemize |
| |
| Some architectures may not support baselining CPU models. s390x supports |
| baselining CPU models. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{modela: CpuModelInfo} |
| Not documented |
| @item @code{modelb: CpuModelInfo} |
| Not documented |
| @end table |
| |
| @b{Returns:} |
| a CpuModelBaselineInfo. Returns an error if baselining CPU models is |
| not supported, if a model cannot be used, if a model contains |
| an unknown cpu definition name, unknown properties or properties |
| with wrong types. |
| |
| @b{Since:} |
| 2.8.0 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} AddfdInfo |
| |
| Information about a file descriptor that was added to an fd set. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{fdset-id: int} |
| The ID of the fd set that @code{fd} was added to. |
| @item @code{fd: int} |
| The file descriptor that was received via SCM rights and |
| added to the fd set. |
| @end table |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} add-fd |
| |
| Add a file descriptor, that was passed via SCM rights, to an fd set. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{fdset-id: int} (optional) |
| The ID of the fd set to add the file descriptor to. |
| @item @code{opaque: string} (optional) |
| A free-form string that can be used to describe the fd. |
| @end table |
| |
| @b{Returns:} |
| @code{AddfdInfo} on success |
| |
| If file descriptor was not received, FdNotSupplied |
| |
| If @code{fdset-id} is a negative value, InvalidParameterValue |
| |
| @b{Notes:} |
| The list of fd sets is shared by all monitor connections. |
| |
| If @code{fdset-id} is not specified, a new fd set will be created. |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "add-fd", "arguments": @{ "fdset-id": 1 @} @} |
| <- @{ "return": @{ "fdset-id": 1, "fd": 3 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} remove-fd |
| |
| Remove a file descriptor from an fd set. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{fdset-id: int} |
| The ID of the fd set that the file descriptor belongs to. |
| @item @code{fd: int} (optional) |
| The file descriptor that is to be removed. |
| @end table |
| |
| @b{Returns:} |
| Nothing on success |
| If @code{fdset-id} or @code{fd} is not found, FdNotFound |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @b{Notes:} |
| The list of fd sets is shared by all monitor connections. |
| |
| If @code{fd} is not specified, all file descriptors in @code{fdset-id} |
| will be removed. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "remove-fd", "arguments": @{ "fdset-id": 1, "fd": 3 @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} FdsetFdInfo |
| |
| Information about a file descriptor that belongs to an fd set. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{fd: int} |
| The file descriptor value. |
| @item @code{opaque: string} (optional) |
| A free-form string that can be used to describe the fd. |
| @end table |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} FdsetInfo |
| |
| Information about an fd set. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{fdset-id: int} |
| The ID of the fd set. |
| @item @code{fds: array of FdsetFdInfo} |
| A list of file descriptors that belong to this fd set. |
| @end table |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-fdsets |
| |
| Return information describing all fd sets. |
| |
| @b{Returns:} |
| A list of @code{FdsetInfo} |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @b{Note:} |
| The list of fd sets is shared by all monitor connections. |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-fdsets" @} |
| <- @{ "return": [ |
| @{ |
| "fds": [ |
| @{ |
| "fd": 30, |
| "opaque": "rdonly:/path/to/file" |
| @}, |
| @{ |
| "fd": 24, |
| "opaque": "rdwr:/path/to/file" |
| @} |
| ], |
| "fdset-id": 1 |
| @}, |
| @{ |
| "fds": [ |
| @{ |
| "fd": 28 |
| @}, |
| @{ |
| "fd": 29 |
| @} |
| ], |
| "fdset-id": 0 |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} TargetInfo |
| |
| Information describing the QEMU target. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{arch: string} |
| the target architecture (eg "x86_64", "i386", etc) |
| @end table |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-target |
| |
| Return information about the target for this QEMU |
| |
| @b{Returns:} |
| TargetInfo |
| |
| @b{Since:} |
| 1.2.0 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} AcpiTableOptions |
| |
| Specify an ACPI table on the command line to load. |
| |
| At most one of @code{file} and @code{data} can be specified. The list of files specified |
| by any one of them is loaded and concatenated in order. If both are omitted, |
| @code{data} is implied. |
| |
| Other fields / optargs can be used to override fields of the generic ACPI |
| table header; refer to the ACPI specification 5.0, section 5.2.6 System |
| Description Table Header. If a header field is not overridden, then the |
| corresponding value from the concatenated blob is used (in case of @code{file}), or |
| it is filled in with a hard-coded value (in case of @code{data}). |
| |
| String fields are copied into the matching ACPI member from lowest address |
| upwards, and silently truncated / NUL-padded to length. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{sig: string} (optional) |
| table signature / identifier (4 bytes) |
| @item @code{rev: int} (optional) |
| table revision number (dependent on signature, 1 byte) |
| @item @code{oem_id: string} (optional) |
| OEM identifier (6 bytes) |
| @item @code{oem_table_id: string} (optional) |
| OEM table identifier (8 bytes) |
| @item @code{oem_rev: int} (optional) |
| OEM-supplied revision number (4 bytes) |
| @item @code{asl_compiler_id: string} (optional) |
| identifier of the utility that created the table |
| (4 bytes) |
| @item @code{asl_compiler_rev: int} (optional) |
| revision number of the utility that created the |
| table (4 bytes) |
| @item @code{file: string} (optional) |
| colon (:) separated list of pathnames to load and |
| concatenate as table data. The resultant binary blob is expected to |
| have an ACPI table header. At least one file is required. This field |
| excludes @code{data}. |
| @item @code{data: string} (optional) |
| colon (:) separated list of pathnames to load and |
| concatenate as table data. The resultant binary blob must not have an |
| ACPI table header. At least one file is required. This field excludes |
| @code{file}. |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} CommandLineParameterType |
| |
| Possible types for an option parameter. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{string} |
| accepts a character string |
| @item @code{boolean} |
| accepts "on" or "off" |
| @item @code{number} |
| accepts a number |
| @item @code{size} |
| accepts a number followed by an optional suffix (K)ilo, |
| (M)ega, (G)iga, (T)era |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CommandLineParameterInfo |
| |
| Details about a single parameter of a command line option. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{name: string} |
| parameter name |
| @item @code{type: CommandLineParameterType} |
| parameter @code{CommandLineParameterType} |
| @item @code{help: string} (optional) |
| human readable text string, not suitable for parsing. |
| @item @code{default: string} (optional) |
| default value string (since 2.1) |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} CommandLineOptionInfo |
| |
| Details about a command line option, including its list of parameter details |
| |
| @b{Members:} |
| @table @asis |
| @item @code{option: string} |
| option name |
| @item @code{parameters: array of CommandLineParameterInfo} |
| an array of @code{CommandLineParameterInfo} |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-command-line-options |
| |
| Query command line option schema. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{option: string} (optional) |
| option name |
| @end table |
| |
| @b{Returns:} |
| list of @code{CommandLineOptionInfo} for all options (or for the given |
| @code{option}). Returns an error if the given @code{option} doesn't exist. |
| |
| @b{Since:} |
| 1.5 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-command-line-options", |
| "arguments": @{ "option": "option-rom" @} @} |
| <- @{ "return": [ |
| @{ |
| "parameters": [ |
| @{ |
| "name": "romfile", |
| "type": "string" |
| @}, |
| @{ |
| "name": "bootindex", |
| "type": "number" |
| @} |
| ], |
| "option": "option-rom" |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} X86CPURegister32 |
| |
| A X86 32-bit register |
| |
| @b{Values:} |
| @table @asis |
| @item @code{EAX} |
| Not documented |
| @item @code{EBX} |
| Not documented |
| @item @code{ECX} |
| Not documented |
| @item @code{EDX} |
| Not documented |
| @item @code{ESP} |
| Not documented |
| @item @code{EBP} |
| Not documented |
| @item @code{ESI} |
| Not documented |
| @item @code{EDI} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} X86CPUFeatureWordInfo |
| |
| Information about a X86 CPU feature word |
| |
| @b{Members:} |
| @table @asis |
| @item @code{cpuid-input-eax: int} |
| Input EAX value for CPUID instruction for that feature word |
| @item @code{cpuid-input-ecx: int} (optional) |
| Input ECX value for CPUID instruction for that |
| feature word |
| @item @code{cpuid-register: X86CPURegister32} |
| Output register containing the feature bits |
| @item @code{features: int} |
| value of output register, containing the feature bits |
| @end table |
| |
| @b{Since:} |
| 1.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} DummyForceArrays |
| |
| Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally |
| |
| @b{Members:} |
| @table @asis |
| @item @code{unused: array of X86CPUFeatureWordInfo} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} NumaOptionsType |
| |
| |
| |
| @b{Values:} |
| @table @asis |
| @item @code{node} |
| NUMA nodes configuration |
| @item @code{dist} |
| NUMA distance configuration (since 2.10) |
| @item @code{cpu} |
| property based CPU(s) to node mapping (Since: 2.10) |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NumaOptions |
| |
| A discriminated record of NUMA options. (for OptsVisitor) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: NumaOptionsType} |
| Not documented |
| @item The members of @code{NumaNodeOptions} when @code{type} is @t{"node"} |
| @item The members of @code{NumaDistOptions} when @code{type} is @t{"dist"} |
| @item The members of @code{NumaCpuOptions} when @code{type} is @t{"cpu"} |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NumaNodeOptions |
| |
| Create a guest NUMA node. (for OptsVisitor) |
| |
| @b{Members:} |
| @table @asis |
| @item @code{nodeid: int} (optional) |
| NUMA node ID (increase by 1 from 0 if omitted) |
| @item @code{cpus: array of int} (optional) |
| VCPUs belonging to this node (assign VCPUS round-robin |
| if omitted) |
| @item @code{mem: int} (optional) |
| memory size of this node; mutually exclusive with @code{memdev}. |
| Equally divide total memory among nodes if both @code{mem} and @code{memdev} are |
| omitted. |
| @item @code{memdev: string} (optional) |
| memory backend object. If specified for one node, |
| it must be specified for all nodes. |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NumaDistOptions |
| |
| Set the distance between 2 NUMA nodes. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{src: int} |
| source NUMA node. |
| @item @code{dst: int} |
| destination NUMA node. |
| @item @code{val: int} |
| NUMA distance from source node to destination node. |
| When a node is unreachable from another node, set the distance |
| between them to 255. |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} NumaCpuOptions |
| |
| Option "-numa cpu" overrides default cpu to node mapping. |
| It accepts the same set of cpu properties as returned by |
| query-hotpluggable-cpus[].props, where node-id could be used to |
| override default node mapping. |
| |
| @b{Members:} |
| @table @asis |
| @item The members of @code{CpuInstanceProperties} |
| @end table |
| |
| @b{Since:} |
| 2.10 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Enum} HostMemPolicy |
| |
| Host memory policy types |
| |
| @b{Values:} |
| @table @asis |
| @item @code{default} |
| restore default policy, remove any nondefault policy |
| @item @code{preferred} |
| set the preferred host nodes for allocation |
| @item @code{bind} |
| a strict policy that restricts memory allocation to the |
| host nodes specified |
| @item @code{interleave} |
| memory allocations are interleaved across the set |
| of host nodes specified |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} Memdev |
| |
| Information about memory backend |
| |
| @b{Members:} |
| @table @asis |
| @item @code{id: string} (optional) |
| backend's ID if backend has 'id' property (since 2.9) |
| @item @code{size: int} |
| memory backend size |
| @item @code{merge: boolean} |
| enables or disables memory merge support |
| @item @code{dump: boolean} |
| includes memory backend's memory in a core dump or not |
| @item @code{prealloc: boolean} |
| enables or disables memory preallocation |
| @item @code{host-nodes: array of int} |
| host nodes for its memory policy |
| @item @code{policy: HostMemPolicy} |
| memory policy of memory backend |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-memdev |
| |
| Returns information for all memory backends. |
| |
| @b{Returns:} |
| a list of @code{Memdev}. |
| |
| @b{Since:} |
| 2.1 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-memdev" @} |
| <- @{ "return": [ |
| @{ |
| "id": "mem1", |
| "size": 536870912, |
| "merge": false, |
| "dump": true, |
| "prealloc": false, |
| "host-nodes": [0, 1], |
| "policy": "bind" |
| @}, |
| @{ |
| "size": 536870912, |
| "merge": false, |
| "dump": true, |
| "prealloc": true, |
| "host-nodes": [2, 3], |
| "policy": "preferred" |
| @} |
| ] |
| @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} PCDIMMDeviceInfo |
| |
| PCDIMMDevice state information |
| |
| @b{Members:} |
| @table @asis |
| @item @code{id: string} (optional) |
| device's ID |
| @item @code{addr: int} |
| physical address, where device is mapped |
| @item @code{size: int} |
| size of memory that the device provides |
| @item @code{slot: int} |
| slot number at which device is plugged in |
| @item @code{node: int} |
| NUMA node number where device is plugged in |
| @item @code{memdev: string} |
| memory backend linked with device |
| @item @code{hotplugged: boolean} |
| true if device was hotplugged |
| @item @code{hotpluggable: boolean} |
| true if device if could be added/removed while machine is running |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} MemoryDeviceInfo |
| |
| Union containing information about a memory device |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type} |
| One of @t{"dimm"}, @t{"nvdimm"} |
| @item @code{data: PCDIMMDeviceInfo} when @code{type} is @t{"dimm"} |
| @item @code{data: PCDIMMDeviceInfo} when @code{type} is @t{"nvdimm"} |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-memory-devices |
| |
| Lists available memory devices and their state |
| |
| @b{Since:} |
| 2.1 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-memory-devices" @} |
| <- @{ "return": [ @{ "data": |
| @{ "addr": 5368709120, |
| "hotpluggable": true, |
| "hotplugged": true, |
| "id": "d1", |
| "memdev": "/objects/memX", |
| "node": 0, |
| "size": 1073741824, |
| "slot": 0@}, |
| "type": "dimm" |
| @} ] @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} MEM_UNPLUG_ERROR |
| |
| Emitted when memory hot unplug error occurs. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{device: string} |
| device name |
| @item @code{msg: string} |
| Informative message |
| @end table |
| |
| @b{Since:} |
| 2.4 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "MEM_UNPLUG_ERROR" |
| "data": @{ "device": "dimm1", |
| "msg": "acpi: device unplug for unsupported device" |
| @}, |
| "timestamp": @{ "seconds": 1265044230, "microseconds": 450486 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} ACPISlotType |
| |
| |
| |
| @b{Values:} |
| @table @asis |
| @item @code{DIMM} |
| memory slot |
| @item @code{CPU} |
| logical CPU slot (since 2.7) |
| @end table |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} ACPIOSTInfo |
| |
| OSPM Status Indication for a device |
| For description of possible values of @code{source} and @code{status} fields |
| see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{device: string} (optional) |
| device ID associated with slot |
| @item @code{slot: string} |
| slot ID, unique per slot of a given @code{slot-type} |
| @item @code{slot-type: ACPISlotType} |
| type of the slot |
| @item @code{source: int} |
| an integer containing the source event |
| @item @code{status: int} |
| an integer containing the status code |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-acpi-ospm-status |
| |
| Return a list of ACPIOSTInfo for devices that support status |
| reporting via ACPI _OST method. |
| |
| @b{Since:} |
| 2.1 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-acpi-ospm-status" @} |
| <- @{ "return": [ @{ "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0@}, |
| @{ "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0@}, |
| @{ "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0@}, |
| @{ "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0@} |
| ]@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} ACPI_DEVICE_OST |
| |
| Emitted when guest executes ACPI _OST method. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{info: ACPIOSTInfo} |
| OSPM Status Indication |
| @end table |
| |
| @b{Since:} |
| 2.1 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "ACPI_DEVICE_OST", |
| "data": @{ "device": "d1", "slot": "0", |
| "slot-type": "DIMM", "source": 1, "status": 0 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} rtc-reset-reinjection |
| |
| This command will reset the RTC interrupt reinjection backlog. |
| Can be used if another mechanism to synchronize guest time |
| is in effect, for example QEMU guest agent's guest-set-time |
| command. |
| |
| @b{Since:} |
| 2.1 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "rtc-reset-reinjection" @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Event {} RTC_CHANGE |
| |
| Emitted when the guest changes the RTC time. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{offset: int} |
| offset between base RTC clock (as specified by -rtc base), and |
| new RTC clock value |
| @end table |
| |
| @b{Note:} |
| This event is rate-limited. |
| |
| @b{Since:} |
| 0.13.0 |
| |
| @b{Example:} |
| @example |
| <- @{ "event": "RTC_CHANGE", |
| "data": @{ "offset": 78 @}, |
| "timestamp": @{ "seconds": 1267020223, "microseconds": 435656 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} ReplayMode |
| |
| Mode of the replay subsystem. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{none} |
| normal execution mode. Replay or record are not enabled. |
| @item @code{record} |
| record mode. All non-deterministic data is written into the |
| replay log. |
| @item @code{play} |
| replay mode. Non-deterministic data required for system execution |
| is read from the log. |
| @end table |
| |
| @b{Since:} |
| 2.5 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} xen-load-devices-state |
| |
| Load the state of all devices from file. The RAM and the block devices |
| of the VM are not loaded by this command. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{filename: string} |
| the file to load the state of the devices from as binary |
| data. See xen-save-devices-state.txt for a description of the binary |
| format. |
| @end table |
| |
| @b{Since:} |
| 2.7 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "xen-load-devices-state", |
| "arguments": @{ "filename": "/tmp/resume" @} @} |
| <- @{ "return": @{@} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} GICCapability |
| |
| The struct describes capability for a specific GIC (Generic |
| Interrupt Controller) version. These bits are not only decided by |
| QEMU/KVM software version, but also decided by the hardware that |
| the program is running upon. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{version: int} |
| version of GIC to be described. Currently, only 2 and 3 |
| are supported. |
| @item @code{emulated: boolean} |
| whether current QEMU/hardware supports emulated GIC |
| device in user space. |
| @item @code{kernel: boolean} |
| whether current QEMU/hardware supports hardware |
| accelerated GIC device in kernel. |
| @end table |
| |
| @b{Since:} |
| 2.6 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-gic-capabilities |
| |
| This command is ARM-only. It will return a list of GICCapability |
| objects that describe its capability bits. |
| |
| @b{Returns:} |
| a list of GICCapability objects. |
| |
| @b{Since:} |
| 2.6 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-gic-capabilities" @} |
| <- @{ "return": [@{ "version": 2, "emulated": true, "kernel": false @}, |
| @{ "version": 3, "emulated": false, "kernel": true @} ] @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} CpuInstanceProperties |
| |
| List of properties to be used for hotplugging a CPU instance, |
| it should be passed by management with device_add command when |
| a CPU is being hotplugged. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{node-id: int} (optional) |
| NUMA node ID the CPU belongs to |
| @item @code{socket-id: int} (optional) |
| socket number within node/board the CPU belongs to |
| @item @code{core-id: int} (optional) |
| core number within socket the CPU belongs to |
| @item @code{thread-id: int} (optional) |
| thread number within core the CPU belongs to |
| @end table |
| |
| @b{Note:} |
| currently there are 4 properties that could be present |
| but management should be prepared to pass through other |
| properties with device_add command to allow for future |
| interface extension. This also requires the filed names to be kept in |
| sync with the properties passed to -device/device_add. |
| |
| @b{Since:} |
| 2.7 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} HotpluggableCPU |
| |
| |
| |
| @b{Members:} |
| @table @asis |
| @item @code{type: string} |
| CPU object type for usage with device_add command |
| @item @code{props: CpuInstanceProperties} |
| list of properties to be used for hotplugging CPU |
| @item @code{vcpus-count: int} |
| number of logical VCPU threads @code{HotpluggableCPU} provides |
| @item @code{qom-path: string} (optional) |
| link to existing CPU object if CPU is present or |
| omitted if CPU is not present. |
| @end table |
| |
| @b{Since:} |
| 2.7 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-hotpluggable-cpus |
| |
| |
| |
| @b{Returns:} |
| a list of HotpluggableCPU objects. |
| |
| @b{Since:} |
| 2.7 |
| |
| @b{Example:} |
| @example |
| For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8: |
| |
| -> @{ "execute": "query-hotpluggable-cpus" @} |
| <- @{"return": [ |
| @{ "props": @{ "core": 8 @}, "type": "POWER8-spapr-cpu-core", |
| "vcpus-count": 1 @}, |
| @{ "props": @{ "core": 0 @}, "type": "POWER8-spapr-cpu-core", |
| "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"@} |
| ]@}' |
| |
| For pc machine type started with -smp 1,maxcpus=2: |
| |
| -> @{ "execute": "query-hotpluggable-cpus" @} |
| <- @{"return": [ |
| @{ |
| "type": "qemu64-x86_64-cpu", "vcpus-count": 1, |
| "props": @{"core-id": 0, "socket-id": 1, "thread-id": 0@} |
| @}, |
| @{ |
| "qom-path": "/machine/unattached/device[0]", |
| "type": "qemu64-x86_64-cpu", "vcpus-count": 1, |
| "props": @{"core-id": 0, "socket-id": 0, "thread-id": 0@} |
| @} |
| ]@} |
| |
| For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu |
| (Since: 2.11): |
| |
| -> @{ "execute": "query-hotpluggable-cpus" @} |
| <- @{"return": [ |
| @{ |
| "type": "qemu-s390x-cpu", "vcpus-count": 1, |
| "props": @{ "core-id": 1 @} |
| @}, |
| @{ |
| "qom-path": "/machine/unattached/device[0]", |
| "type": "qemu-s390x-cpu", "vcpus-count": 1, |
| "props": @{ "core-id": 0 @} |
| @} |
| ]@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} GuidInfo |
| |
| GUID information. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{guid: string} |
| the globally unique identifier |
| @end table |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-vm-generation-id |
| |
| Show Virtual Machine Generation ID |
| |
| @b{Since:} |
| 2.9 |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} SevState |
| |
| An enumeration of SEV state information used during @code{query-sev}. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{uninit} |
| The guest is uninitialized. |
| @item @code{launch-update} |
| The guest is currently being launched; plaintext data and |
| register state is being imported. |
| @item @code{launch-secret} |
| The guest is currently being launched; ciphertext data |
| is being imported. |
| @item @code{running} |
| The guest is fully launched or migrated in. |
| @item @code{send-update} |
| The guest is currently being migrated out to another machine. |
| @item @code{receive-update} |
| The guest is currently being migrated from another machine. |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftp {Object} SevInfo |
| |
| Information about Secure Encrypted Virtualization (SEV) support |
| |
| @b{Members:} |
| @table @asis |
| @item @code{enabled: boolean} |
| true if SEV is active |
| @item @code{api-major: int} |
| SEV API major version |
| @item @code{api-minor: int} |
| SEV API minor version |
| @item @code{build-id: int} |
| SEV FW build id |
| @item @code{policy: int} |
| SEV policy value |
| @item @code{state: SevState} |
| SEV guest state |
| @item @code{handle: int} |
| SEV firmware handle |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-sev |
| |
| Returns information about SEV |
| |
| @b{Returns:} |
| @code{SevInfo} |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-sev" @} |
| <- @{ "return": @{ "enabled": true, "api-major" : 0, "api-minor" : 0, |
| "build-id" : 0, "policy" : 0, "state" : "running", |
| "handle" : 1 @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} SevLaunchMeasureInfo |
| |
| SEV Guest Launch measurement information |
| |
| @b{Members:} |
| @table @asis |
| @item @code{data: string} |
| the measurement value encoded in base64 |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-sev-launch-measure |
| |
| Query the SEV guest launch information. |
| |
| @b{Returns:} |
| The @code{SevLaunchMeasureInfo} for the guest |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-sev-launch-measure" @} |
| <- @{ "return": @{ "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Object} SevCapability |
| |
| The struct describes capability for a Secure Encrypted Virtualization |
| feature. |
| |
| @b{Members:} |
| @table @asis |
| @item @code{pdh: string} |
| Platform Diffie-Hellman key (base64 encoded) |
| @item @code{cert-chain: string} |
| PDH certificate chain (base64 encoded) |
| @item @code{cbitpos: int} |
| C-bit location in page table entry |
| @item @code{reduced-phys-bits: int} |
| Number of physical Address bit reduction when SEV is |
| enabled |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Command {} query-sev-capabilities |
| |
| This command is used to get the SEV capabilities, and is supported on AMD |
| X86 platforms only. |
| |
| @b{Returns:} |
| SevCapability objects. |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| -> @{ "execute": "query-sev-capabilities" @} |
| <- @{ "return": @{ "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE", |
| "cbitpos": 47, "reduced-phys-bits": 5@}@} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftp {Enum} CommandDropReason |
| |
| Reasons that caused one command to be dropped. |
| |
| @b{Values:} |
| @table @asis |
| @item @code{queue-full} |
| the command queue is full. This can only occur when |
| the client sends a new non-oob command before the |
| response to the previous non-oob command has been |
| received. |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @end deftp |
| |
| |
| |
| @deftypefn Event {} COMMAND_DROPPED |
| |
| Emitted when a command is dropped due to some reason. Commands can |
| only be dropped when the oob capability is enabled. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{id: value} |
| The dropped command's "id" field. |
| @item @code{reason: CommandDropReason} |
| The reason why the command is dropped. |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| @{ "event": "COMMAND_DROPPED", |
| "data": @{"result": @{"id": "libvirt-102", |
| "reason": "queue-full" @} @} @} |
| @end example |
| |
| @end deftypefn |
| |
| |
| |
| @deftypefn Command {} x-oob-test |
| |
| Test OOB functionality. When sending this command with lock=true, |
| it'll try to hang the dispatcher. When sending it with lock=false, |
| it'll try to notify the locked thread to continue. Note: it should |
| only be used by QMP test program rather than anything else. |
| |
| @b{Arguments:} |
| @table @asis |
| @item @code{lock: boolean} |
| Not documented |
| @end table |
| |
| @b{Since:} |
| 2.12 |
| |
| @b{Example:} |
| @example |
| @{ "execute": "x-oob-test", |
| "arguments": @{ "lock": true @} @} |
| @end example |
| |
| @end deftypefn |
| |