diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/colo-proxy.txt | 4 | ||||
| -rw-r--r-- | docs/lockcnt.txt | 277 | ||||
| -rw-r--r-- | docs/multiple-iothreads.txt | 13 | ||||
| -rw-r--r-- | docs/pcie.txt | 12 | ||||
| -rw-r--r-- | docs/qapi-code-gen.txt | 180 | ||||
| -rw-r--r-- | docs/qemu-ga-ref.texi | 78 | ||||
| -rw-r--r-- | docs/qemu-qmp-ref.texi | 78 | ||||
| -rw-r--r-- | docs/qemu_logo.pdf | bin | 0 -> 9117 bytes | |||
| -rw-r--r-- | docs/qmp-commands.txt | 3824 | ||||
| -rw-r--r-- | docs/qmp-events.txt | 731 | ||||
| -rw-r--r-- | docs/qmp-intro.txt | 3 | ||||
| -rw-r--r-- | docs/replay.txt | 14 | ||||
| -rw-r--r-- | docs/specs/fw_cfg.txt | 36 | ||||
| -rw-r--r-- | docs/specs/pci-ids.txt | 3 | ||||
| -rw-r--r-- | docs/specs/vhost-user.txt | 16 | ||||
| -rw-r--r-- | docs/usb-storage.txt | 2 | ||||
| -rw-r--r-- | docs/usb2.txt | 2 |
17 files changed, 657 insertions, 4616 deletions
diff --git a/docs/colo-proxy.txt b/docs/colo-proxy.txt index 76767cb34f..c4941de198 100644 --- a/docs/colo-proxy.txt +++ b/docs/colo-proxy.txt @@ -158,7 +158,9 @@ secondary. == Usage == -Here, we use demo ip and port discribe more clearly. +Here is an example using demonstration IP and port addresses to more +clearly describe the usage. + Primary(ip:3.3.3.3): -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 diff --git a/docs/lockcnt.txt b/docs/lockcnt.txt new file mode 100644 index 0000000000..2a79b3205b --- /dev/null +++ b/docs/lockcnt.txt @@ -0,0 +1,277 @@ +DOCUMENTATION FOR LOCKED COUNTERS (aka QemuLockCnt) +=================================================== + +QEMU often uses reference counts to track data structures that are being +accessed and should not be freed. For example, a loop that invoke +callbacks like this is not safe: + + QLIST_FOREACH_SAFE(ioh, &io_handlers, next, pioh) { + if (ioh->revents & G_IO_OUT) { + ioh->fd_write(ioh->opaque); + } + } + +QLIST_FOREACH_SAFE protects against deletion of the current node (ioh) +by stashing away its "next" pointer. However, ioh->fd_write could +actually delete the next node from the list. The simplest way to +avoid this is to mark the node as deleted, and remove it from the +list in the above loop: + + QLIST_FOREACH_SAFE(ioh, &io_handlers, next, pioh) { + if (ioh->deleted) { + QLIST_REMOVE(ioh, next); + g_free(ioh); + } else { + if (ioh->revents & G_IO_OUT) { + ioh->fd_write(ioh->opaque); + } + } + } + +If however this loop must also be reentrant, i.e. it is possible that +ioh->fd_write invokes the loop again, some kind of counting is needed: + + walking_handlers++; + QLIST_FOREACH_SAFE(ioh, &io_handlers, next, pioh) { + if (ioh->deleted) { + if (walking_handlers == 1) { + QLIST_REMOVE(ioh, next); + g_free(ioh); + } + } else { + if (ioh->revents & G_IO_OUT) { + ioh->fd_write(ioh->opaque); + } + } + } + walking_handlers--; + +One may think of using the RCU primitives, rcu_read_lock() and +rcu_read_unlock(); effectively, the RCU nesting count would take +the place of the walking_handlers global variable. Indeed, +reference counting and RCU have similar purposes, but their usage in +general is complementary: + +- reference counting is fine-grained and limited to a single data + structure; RCU delays reclamation of *all* RCU-protected data + structures; + +- reference counting works even in the presence of code that keeps + a reference for a long time; RCU critical sections in principle + should be kept short; + +- reference counting is often applied to code that is not thread-safe + but is reentrant; in fact, usage of reference counting in QEMU predates + the introduction of threads by many years. RCU is generally used to + protect readers from other threads freeing memory after concurrent + modifications to a data structure. + +- reclaiming data can be done by a separate thread in the case of RCU; + this can improve performance, but also delay reclamation undesirably. + With reference counting, reclamation is deterministic. + +This file documents QemuLockCnt, an abstraction for using reference +counting in code that has to be both thread-safe and reentrant. + + +QemuLockCnt concepts +-------------------- + +A QemuLockCnt comprises both a counter and a mutex; it has primitives +to increment and decrement the counter, and to take and release the +mutex. The counter notes how many visits to the data structures are +taking place (the visits could be from different threads, or there could +be multiple reentrant visits from the same thread). The basic rules +governing the counter/mutex pair then are the following: + +- Data protected by the QemuLockCnt must not be freed unless the + counter is zero and the mutex is taken. + +- A new visit cannot be started while the counter is zero and the + mutex is taken. + +Most of the time, the mutex protects all writes to the data structure, +not just frees, though there could be cases where this is not necessary. + +Reads, instead, can be done without taking the mutex, as long as the +readers and writers use the same macros that are used for RCU, for +example atomic_rcu_read, atomic_rcu_set, QLIST_FOREACH_RCU, etc. This is +because the reads are done outside a lock and a set or QLIST_INSERT_HEAD +can happen concurrently with the read. The RCU API ensures that the +processor and the compiler see all required memory barriers. + +This could be implemented simply by protecting the counter with the +mutex, for example: + + // (1) + qemu_mutex_lock(&walking_handlers_mutex); + walking_handlers++; + qemu_mutex_unlock(&walking_handlers_mutex); + + ... + + // (2) + qemu_mutex_lock(&walking_handlers_mutex); + if (--walking_handlers == 0) { + QLIST_FOREACH_SAFE(ioh, &io_handlers, next, pioh) { + if (ioh->deleted) { + QLIST_REMOVE(ioh, next); + g_free(ioh); + } + } + } + qemu_mutex_unlock(&walking_handlers_mutex); + +Here, no frees can happen in the code represented by the ellipsis. +If another thread is executing critical section (2), that part of +the code cannot be entered, because the thread will not be able +to increment the walking_handlers variable. And of course +during the visit any other thread will see a nonzero value for +walking_handlers, as in the single-threaded code. + +Note that it is possible for multiple concurrent accesses to delay +the cleanup arbitrarily; in other words, for the walking_handlers +counter to never become zero. For this reason, this technique is +more easily applicable if concurrent access to the structure is rare. + +However, critical sections are easy to forget since you have to do +them for each modification of the counter. QemuLockCnt ensures that +all modifications of the counter take the lock appropriately, and it +can also be more efficient in two ways: + +- it avoids taking the lock for many operations (for example + incrementing the counter while it is non-zero); + +- on some platforms, one can implement QemuLockCnt to hold the lock + and the mutex in a single word, making the fast path no more expensive + than simply managing a counter using atomic operations (see + docs/atomics.txt). This can be very helpful if concurrent access to + the data structure is expected to be rare. + + +Using the same mutex for frees and writes can still incur some small +inefficiencies; for example, a visit can never start if the counter is +zero and the mutex is taken---even if the mutex is taken by a write, +which in principle need not block a visit of the data structure. +However, these are usually not a problem if any of the following +assumptions are valid: + +- concurrent access is possible but rare + +- writes are rare + +- writes are frequent, but this kind of write (e.g. appending to a + list) has a very small critical section. + +For example, QEMU uses QemuLockCnt to manage an AioContext's list of +bottom halves and file descriptor handlers. Modifications to the list +of file descriptor handlers are rare. Creation of a new bottom half is +frequent and can happen on a fast path; however: 1) it is almost never +concurrent with a visit to the list of bottom halves; 2) it only has +three instructions in the critical path, two assignments and a smp_wmb(). + + +QemuLockCnt API +--------------- + +The QemuLockCnt API is described in include/qemu/thread.h. + + +QemuLockCnt usage +----------------- + +This section explains the typical usage patterns for QemuLockCnt functions. + +Setting a variable to a non-NULL value can be done between +qemu_lockcnt_lock and qemu_lockcnt_unlock: + + qemu_lockcnt_lock(&xyz_lockcnt); + if (!xyz) { + new_xyz = g_new(XYZ, 1); + ... + atomic_rcu_set(&xyz, new_xyz); + } + qemu_lockcnt_unlock(&xyz_lockcnt); + +Accessing the value can be done between qemu_lockcnt_inc and +qemu_lockcnt_dec: + + qemu_lockcnt_inc(&xyz_lockcnt); + if (xyz) { + XYZ *p = atomic_rcu_read(&xyz); + ... + /* Accesses can now be done through "p". */ + } + qemu_lockcnt_dec(&xyz_lockcnt); + +Freeing the object can similarly use qemu_lockcnt_lock and +qemu_lockcnt_unlock, but you also need to ensure that the count +is zero (i.e. there is no concurrent visit). Because qemu_lockcnt_inc +takes the QemuLockCnt's lock, the count cannot become non-zero while +the object is being freed. Freeing an object looks like this: + + qemu_lockcnt_lock(&xyz_lockcnt); + if (!qemu_lockcnt_count(&xyz_lockcnt)) { + g_free(xyz); + xyz = NULL; + } + qemu_lockcnt_unlock(&xyz_lockcnt); + +If an object has to be freed right after a visit, you can combine +the decrement, the locking and the check on count as follows: + + qemu_lockcnt_inc(&xyz_lockcnt); + if (xyz) { + XYZ *p = atomic_rcu_read(&xyz); + ... + /* Accesses can now be done through "p". */ + } + if (qemu_lockcnt_dec_and_lock(&xyz_lockcnt)) { + g_free(xyz); + xyz = NULL; + qemu_lockcnt_unlock(&xyz_lockcnt); + } + +QemuLockCnt can also be used to access a list as follows: + + qemu_lockcnt_inc(&io_handlers_lockcnt); + QLIST_FOREACH_RCU(ioh, &io_handlers, pioh) { + if (ioh->revents & G_IO_OUT) { + ioh->fd_write(ioh->opaque); + } + } + + if (qemu_lockcnt_dec_and_lock(&io_handlers_lockcnt)) { + QLIST_FOREACH_SAFE(ioh, &io_handlers, next, pioh) { + if (ioh->deleted) { + QLIST_REMOVE(ioh, next); + g_free(ioh); + } + } + qemu_lockcnt_unlock(&io_handlers_lockcnt); + } + +Again, the RCU primitives are used because new items can be added to the +list during the walk. QLIST_FOREACH_RCU ensures that the processor and +the compiler see the appropriate memory barriers. + +An alternative pattern uses qemu_lockcnt_dec_if_lock: + + qemu_lockcnt_inc(&io_handlers_lockcnt); + QLIST_FOREACH_SAFE_RCU(ioh, &io_handlers, next, pioh) { + if (ioh->deleted) { + if (qemu_lockcnt_dec_if_lock(&io_handlers_lockcnt)) { + QLIST_REMOVE(ioh, next); + g_free(ioh); + qemu_lockcnt_inc_and_unlock(&io_handlers_lockcnt); + } + } else { + if (ioh->revents & G_IO_OUT) { + ioh->fd_write(ioh->opaque); + } + } + } + qemu_lockcnt_dec(&io_handlers_lockcnt); + +Here you can use qemu_lockcnt_dec instead of qemu_lockcnt_dec_and_lock, +because there is no special task to do if the count goes from 1 to 0. diff --git a/docs/multiple-iothreads.txt b/docs/multiple-iothreads.txt index 0e7cdb2c28..e4d340bbb7 100644 --- a/docs/multiple-iothreads.txt +++ b/docs/multiple-iothreads.txt @@ -84,9 +84,8 @@ How to synchronize with an IOThread AioContext is not thread-safe so some rules must be followed when using file descriptors, event notifiers, timers, or BHs across threads: -1. AioContext functions can be called safely from file descriptor, event -notifier, timer, or BH callbacks invoked by the AioContext. No locking is -necessary. +1. AioContext functions can always be called safely. They handle their +own locking internally. 2. Other threads wishing to access the AioContext must use aio_context_acquire()/aio_context_release() for mutual exclusion. Once the @@ -94,16 +93,14 @@ context is acquired no other thread can access it or run event loop iterations in this AioContext. aio_context_acquire()/aio_context_release() calls may be nested. This -means you can call them if you're not sure whether #1 applies. +means you can call them if you're not sure whether #2 applies. There is currently no lock ordering rule if a thread needs to acquire multiple AioContexts simultaneously. Therefore, it is only safe for code holding the QEMU global mutex to acquire other AioContexts. -Side note: the best way to schedule a function call across threads is to create -a BH in the target AioContext beforehand and then call qemu_bh_schedule(). No -acquire/release or locking is needed for the qemu_bh_schedule() call. But be -sure to acquire the AioContext for aio_bh_new() if necessary. +Side note: the best way to schedule a function call across threads is to call +aio_bh_schedule_oneshot(). No acquire/release or locking is needed. AioContext and the block layer ------------------------------ diff --git a/docs/pcie.txt b/docs/pcie.txt index 9fb20aaed9..5bada24a15 100644 --- a/docs/pcie.txt +++ b/docs/pcie.txt @@ -110,18 +110,18 @@ Plug only PCI Express devices into PCI Express Ports. -device ioh3420,id=root_port1,chassis=x,slot=y[,bus=pcie.0][,addr=z] \ -device <dev>,bus=root_port1 2.2.2 Using multi-function PCI Express Root Ports: - -device ioh3420,id=root_port1,multifunction=on,chassis=x,slot=y[,bus=pcie.0][,addr=z.0] \ - -device ioh3420,id=root_port2,chassis=x1,slot=y1[,bus=pcie.0][,addr=z.1] \ - -device ioh3420,id=root_port3,chassis=x2,slot=y2[,bus=pcie.0][,addr=z.2] \ -2.2.2 Plugging a PCI Express device into a Switch: + -device ioh3420,id=root_port1,multifunction=on,chassis=x,addr=z.0[,slot=y][,bus=pcie.0] \ + -device ioh3420,id=root_port2,chassis=x1,addr=z.1[,slot=y1][,bus=pcie.0] \ + -device ioh3420,id=root_port3,chassis=x2,addr=z.2[,slot=y2][,bus=pcie.0] \ +2.2.3 Plugging a PCI Express device into a Switch: -device ioh3420,id=root_port1,chassis=x,slot=y[,bus=pcie.0][,addr=z] \ -device x3130-upstream,id=upstream_port1,bus=root_port1[,addr=x] \ -device xio3130-downstream,id=downstream_port1,bus=upstream_port1,chassis=x1,slot=y1[,addr=z1]] \ -device <dev>,bus=downstream_port1 Notes: - - (slot, chassis) pair is mandatory and must be - unique for each PCI Express Root Port. + - (slot, chassis) pair is mandatory and must be unique for each + PCI Express Root Port. slot defaults to 0 when not specified. - 'addr' parameter can be 0 for all the examples above. diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index 2841c5144a..7eb7be12ab 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -44,40 +44,154 @@ Input must be ASCII (although QMP supports full Unicode strings, the QAPI parser does not). At present, there is no place where a QAPI schema requires the use of JSON numbers or null. + +=== Comments === + Comments are allowed; anything between an unquoted # and the following -newline is ignored. Although there is not yet a documentation -generator, a form of stylized comments has developed for consistently -documenting details about an expression and when it was added to the -schema. The documentation is delimited between two lines of ##, then -the first line names the expression, an optional overview is provided, -then individual documentation about each member of 'data' is provided, -and finally, a 'Since: x.y.z' tag lists the release that introduced -the expression. Optional members are tagged with the phrase -'#optional', often with their default value; and extensions added -after the expression was first released are also given a '(since -x.y.z)' comment. For example: - - ## - # @BlockStats: - # - # Statistics of a virtual block device or a block backing device. - # - # @device: #optional If the stats are for a virtual block device, the name - # corresponding to the virtual block device. - # - # @stats: A @BlockDeviceStats for the device. - # - # @parent: #optional This describes the file block device if it has one. - # - # @backing: #optional This describes the backing block device if it has one. - # (Since 2.0) - # - # Since: 0.14.0 - ## - { 'struct': 'BlockStats', - 'data': {'*device': 'str', 'stats': 'BlockDeviceStats', - '*parent': 'BlockStats', - '*backing': 'BlockStats'} } +newline is ignored. + +A multi-line comment that starts and ends with a '##' line is a +documentation comment. These are parsed by the documentation +generator, which recognizes certain markup detailed below. + + +==== Documentation markup ==== + +Comment text starting with '=' is a section title: + + # = Section title + +Double the '=' for a subsection title: + + # == Subection title + +'|' denotes examples: + + # | Text of the example, may span + # | multiple lines + +'*' starts an itemized list: + + # * First item, may span + # multiple lines + # * Second item + +You can also use '-' instead of '*'. + +A decimal number followed by '.' starts a numbered list: + + # 1. First item, may span + # multiple lines + # 2. Second item + +The actual number doesn't matter. You could even use '*' instead of +'2.' for the second item. + +Lists can't be nested. Blank lines are currently not supported within +lists. + +Additional whitespace between the initial '#' and the comment text is +permitted. + +*foo* and _foo_ are for strong and emphasis styles respectively (they +do not work over multiple lines). @foo is used to reference a name in +the schema. + +Example: + +## +# = Section +# == Subsection +# +# Some text foo with *strong* and _emphasis_ +# 1. with a list +# 2. like that +# +# And some code: +# | $ echo foo +# | -> do this +# | <- get that +# +## + + +==== Expression documentation ==== + +Each expression that isn't an include directive must be preceded by a +documentation block. Such blocks are called expression documentation +blocks. + +The documentation block consists of a first line naming the +expression, an optional overview, a description of each argument (for +commands and events) or member (for structs, unions and alternates), +and optional tagged sections. + +FIXME: the parser accepts these things in almost any order. + +Optional arguments / members are tagged with the phrase '#optional', +often with their default value; and extensions added after the +expression was first released are also given a '(since x.y.z)' +comment. + +A tagged section starts with one of the following words: +"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". +The section ends with the start of a new section. + +A 'Since: x.y.z' tagged section lists the release that introduced the +expression. + +For example: + +## +# @BlockStats: +# +# Statistics of a virtual block device or a block backing device. +# +# @device: #optional If the stats are for a virtual block device, the name +# corresponding to the virtual block device. +# +# @node-name: #optional The node name of the device. (since 2.3) +# +# ... more members ... +# +# Since: 0.14.0 +## +{ 'struct': 'BlockStats', + 'data': {'*device': 'str', '*node-name': 'str', + ... more members ... } } + +## +# @query-blockstats: +# +# Query the @BlockStats for all virtual block devices. +# +# @query-nodes: #optional If true, the command will query all the +# block nodes ... explain, explain ... (since 2.3) +# +# Returns: A list of @BlockStats for each virtual block devices. +# +# Since: 0.14.0 +# +# Example: +# +# -> { "execute": "query-blockstats" } +# <- { +# ... lots of output ... +# } +# +## +{ 'command': 'query-blockstats', + 'data': { '*query-nodes': 'bool' }, + 'returns': ['BlockStats'] } + +==== Free-form documentation ==== + +A documentation block that isn't an expression documentation block is +a free-form documentation block. These may be used to provide +additional text and structuring content. + + +=== Schema overview === The schema sets up a series of types, as well as commands and events that will use those types. Forward references are allowed: the parser diff --git a/docs/qemu-ga-ref.texi b/docs/qemu-ga-ref.texi new file mode 100644 index 0000000000..87cc8d01a5 --- /dev/null +++ b/docs/qemu-ga-ref.texi @@ -0,0 +1,78 @@ +\input texinfo +@setfilename qemu-ga-ref.info + +@exampleindent 0 +@paragraphindent 0 + +@settitle QEMU Guest Agent Protocol Reference + +@iftex +@center @image{docs/qemu_logo} +@end iftex + +@copying +This is the QEMU Guest Agent Protocol reference manual. + +Copyright @copyright{} 2016 The QEMU Project developers + +@quotation +This manual is free documentation: you can redistribute it and/or +modify it under the terms of the GNU General Public License as +published by the Free Software Foundation, either version 2 of the +License, or (at your option) any later version. + +This manual is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this manual. If not, see http://www.gnu.org/licenses/. +@end quotation +@end copying + +@dircategory QEMU +@direntry +* QEMU-GA-Ref: (qemu-ga-ref). QEMU Guest Agent Protocol Reference +@end direntry + +@titlepage +@title Guest Agent Protocol Reference Manual +@subtitle QEMU version @value{VERSION} +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top QEMU Guest Agent protocol reference +@end ifnottex + +@menu +* API Reference:: +* Commands and Events Index:: +* Data Types Index:: +@end menu + +@node API Reference +@chapter API Reference + +@c for texi2pod: +@c man begin DESCRIPTION + +@include qemu-ga-qapi.texi + +@c man end + +@node Commands and Events Index +@unnumbered Commands and Events Index +@printindex fn + +@node Data Types Index +@unnumbered Data Types Index +@printindex tp + +@bye diff --git a/docs/qemu-qmp-ref.texi b/docs/qemu-qmp-ref.texi new file mode 100644 index 0000000000..818e52573b --- /dev/null +++ b/docs/qemu-qmp-ref.texi @@ -0,0 +1,78 @@ +\input texinfo +@setfilename qemu-qmp-ref.info + +@exampleindent 0 +@paragraphindent 0 + +@settitle QEMU QMP Reference Manual + +@iftex +@center @image{docs/qemu_logo} +@end iftex + +@copying +This is the QEMU QMP reference manual. + +Copyright @copyright{} 2016 The QEMU Project developers + +@quotation +This manual is free documentation: you can redistribute it and/or +modify it under the terms of the GNU General Public License as +published by the Free Software Foundation, either version 2 of the +License, or (at your option) any later version. + +This manual is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this manual. If not, see http://www.gnu.org/licenses/. +@end quotation +@end copying + +@dircategory QEMU +@direntry +* QEMU-QMP-Ref: (qemu-qmp-ref). QEMU QMP Reference Manual +@end direntry + +@titlepage +@title QMP Reference Manual +@subtitle QEMU version @value{VERSION} +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top QEMU QMP reference +@end ifnottex + +@menu +* API Reference:: +* Commands and Events Index:: +* Data Types Index:: +@end menu + +@node API Reference +@chapter API Reference + +@c for texi2pod: +@c man begin DESCRIPTION + +@include qemu-qapi.texi + +@c man end + +@node Commands and Events Index +@unnumbered Commands and Events Index +@printindex fn + +@node Data Types Index +@unnumbered Data Types Index +@printindex tp + +@bye diff --git a/docs/qemu_logo.pdf b/docs/qemu_logo.pdf new file mode 100644 index 0000000000..294cb7dec5 --- /dev/null +++ b/docs/qemu_logo.pdf Binary files differdiff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt deleted file mode 100644 index abf210a596..0000000000 --- a/docs/qmp-commands.txt +++ /dev/null @@ -1,3824 +0,0 @@ - QMP Supported Commands - ---------------------- - -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: - --> data issued by the Client -<- Server data response - -Please, refer to the QMP specification (docs/qmp-spec.txt) for detailed -information on the Server command and response formats. - -NOTE: This document is temporary and will be replaced soon. - -1. 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: - - 1. 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 - - 2. DO NOT rely on anything which is not explicit documented - - 3. 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) - -2. Regular Commands -=================== - -Server's responses in the examples below are always a success response, please -refer to the QMP specification for more details on error responses. - -quit ----- - -Quit the emulator. - -Arguments: None. - -Example: - --> { "execute": "quit" } -<- { "return": {} } - -eject ------ - -Eject a removable medium. - -Arguments: - -- "force": force ejection (json-bool, optional) -- "device": block device name (deprecated, use @id instead) - (json-string, optional) -- "id": the name or QOM path of the guest device (json-string, optional) - -Example: - --> { "execute": "eject", "arguments": { "id": "ide0-1-0" } } -<- { "return": {} } - -Note: The "force" argument defaults to false. - -change ------- - -Change a removable medium or VNC configuration. - -Arguments: - -- "device": device name (json-string) -- "target": filename or item (json-string) -- "arg": additional argument (json-string, optional) - -Examples: - -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": {} } - -screendump ----------- - -Save screen into PPM image. - -Arguments: - -- "filename": file path (json-string) - -Example: - --> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } } -<- { "return": {} } - -stop ----- - -Stop the emulator. - -Arguments: None. - -Example: - --> { "execute": "stop" } -<- { "return": {} } - -cont ----- - -Resume emulation. - -Arguments: None. - -Example: - --> { "execute": "cont" } -<- { "return": {} } - -system_wakeup -------------- - -Wakeup guest from suspend. - -Arguments: None. - -Example: - --> { "execute": "system_wakeup" } -<- { "return": {} } - -system_reset ------------- - -Reset the system. - -Arguments: None. - -Example: - --> { "execute": "system_reset" } -<- { "return": {} } - -system_powerdown ----------------- - -Send system power down event. - -Arguments: None. - -Example: - --> { "execute": "system_powerdown" } -<- { "return": {} } - -device_add ----------- - -Add a device. - -Arguments: - -- "driver": the name of the new device's driver (json-string) -- "bus": the device's parent bus (device tree path, json-string, optional) -- "id": the device's ID, must be unique (json-string) -- device properties - -Example: - --> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } } -<- { "return": {} } - -Notes: - -(1) For detailed information about this command, please refer to the - 'docs/qdev-device-use.txt' file. - -(2) It's possible to list device properties by running QEMU with the - "-device DEVICE,\?" command-line argument, where DEVICE is the device's name - -device_del ----------- - -Remove a device. - -Arguments: - -- "id": the device's ID or QOM path (json-string) - -Example: - --> { "execute": "device_del", "arguments": { "id": "net1" } } -<- { "return": {} } - -Example: - --> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } } -<- { "return": {} } - -send-key ----------- - -Send keys to VM. - -Arguments: - -keys array: - - "key": key sequence (a json-array of key union values, - union can be number or qcode enum) - -- hold-time: time to delay key up events, milliseconds. Defaults to 100 - (json-int, optional) - -Example: - --> { "execute": "send-key", - "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, - { "type": "qcode", "data": "alt" }, - { "type": "qcode", "data": "delete" } ] } } -<- { "return": {} } - -cpu ---- - -Set the default CPU. - -Arguments: - -- "index": the CPU's index (json-int) - -Example: - --> { "execute": "cpu", "arguments": { "index": 0 } } -<- { "return": {} } - -Note: CPUs' indexes are obtained with the 'query-cpus' command. - -cpu-add -------- - -Adds virtual cpu - -Arguments: - -- "id": cpu id (json-int) - -Example: - --> { "execute": "cpu-add", "arguments": { "id": 2 } } -<- { "return": {} } - -memsave -------- - -Save to disk virtual memory dump starting at 'val' of size 'size'. - -Arguments: - -- "val": the starting address (json-int) -- "size": the memory size, in bytes (json-int) -- "filename": file path (json-string) -- "cpu": virtual CPU index (json-int, optional) - -Example: - --> { "execute": "memsave", - "arguments": { "val": 10, - "size": 100, - "filename": "/tmp/virtual-mem-dump" } } -<- { "return": {} } - -pmemsave --------- - -Save to disk physical memory dump starting at 'val' of size 'size'. - -Arguments: - -- "val": the starting address (json-int) -- "size": the memory size, in bytes (json-int) -- "filename": file path (json-string) - -Example: - --> { "execute": "pmemsave", - "arguments": { "val": 10, - "size": 100, - "filename": "/tmp/physical-mem-dump" } } -<- { "return": {} } - -inject-nmi ----------- - -Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64). - -Arguments: None. - -Example: - --> { "execute": "inject-nmi" } -<- { "return": {} } - -Note: inject-nmi fails when the guest doesn't support injecting. - -ringbuf-write -------------- - -Write to a ring buffer character device. - -Arguments: - -- "device": ring buffer character device name (json-string) -- "data": data to write (json-string) -- "format": data format (json-string, optional) - - Possible values: "utf8" (default), "base64" - -Example: - --> { "execute": "ringbuf-write", - "arguments": { "device": "foo", - "data": "abcdefgh", - "format": "utf8" } } -<- { "return": {} } - -ringbuf-read -------------- - -Read from a ring buffer character device. - -Arguments: - -- "device": ring buffer character device name (json-string) -- "size": how many bytes to read at most (json-int) - - Number of data bytes, not number of characters in encoded data -- "format": data format (json-string, optional) - - Possible values: "utf8" (default), "base64" - - Naturally, format "utf8" works only when the ring buffer - contains valid UTF-8 text. Invalid UTF-8 sequences get - replaced. Bug: replacement doesn't work. Bug: can screw - up on encountering NUL characters, after the ring buffer - lost data, and when reading stops because the size limit - is reached. - -Example: - --> { "execute": "ringbuf-read", - "arguments": { "device": "foo", - "size": 1000, - "format": "utf8" } } -<- {"return": "abcdefgh"} - -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. - -Arguments: - -- "filename": 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. - -Example: - --> { "execute": "xen-save-devices-state", - "arguments": { "filename": "/tmp/save" } } -<- { "return": {} } - -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. - -Arguments: - -- "filename": 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. - -Example: - --> { "execute": "xen-load-devices-state", - "arguments": { "filename": "/tmp/resume" } } -<- { "return": {} } - -xen-set-global-dirty-log -------- - -Enable or disable the global dirty log mode. - -Arguments: - -- "enable": Enable it or disable it. - -Example: - --> { "execute": "xen-set-global-dirty-log", - "arguments": { "enable": true } } -<- { "return": {} } - -migrate -------- - -Migrate to URI. - -Arguments: - -- "blk": block migration, full disk copy (json-bool, optional) -- "inc": incremental disk copy (json-bool, optional) -- "uri": Destination URI (json-string) - -Example: - --> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } -<- { "return": {} } - -Notes: - -(1) The 'query-migrate' command should be used to check migration's progress - and final result (this information is provided by the 'status' member) -(2) All boolean arguments default to false -(3) The user Monitor's "detach" argument is invalid in QMP and should not - be used - -migrate_cancel --------------- - -Cancel the current migration. - -Arguments: None. - -Example: - --> { "execute": "migrate_cancel" } -<- { "return": {} } - -migrate-incoming ----------------- - -Continue an incoming migration - -Arguments: - -- "uri": Source/listening URI (json-string) - -Example: - --> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } } -<- { "return": {} } - -Notes: - -(1) QEMU must be started with -incoming defer to allow migrate-incoming to - be used -(2) The uri format is the same as for -incoming - -migrate-set-cache-size ----------------------- - -Set cache size to be used by XBZRLE migration, the cache size will be rounded -down to the nearest power of 2 - -Arguments: - -- "value": cache size in bytes (json-int) - -Example: - --> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } } -<- { "return": {} } - -migrate-start-postcopy ----------------------- - -Switch an in-progress migration to postcopy mode. Ignored after the end of -migration (or once already in postcopy). - -Example: --> { "execute": "migrate-start-postcopy" } -<- { "return": {} } - -query-migrate-cache-size ------------------------- - -Show cache size to be used by XBZRLE migration - -returns a json-object with the following information: -- "size" : json-int - -Example: - --> { "execute": "query-migrate-cache-size" } -<- { "return": 67108864 } - -migrate_set_speed ------------------ - -Set maximum speed for migrations. - -Arguments: - -- "value": maximum speed, in bytes per second (json-int) - -Example: - --> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } } -<- { "return": {} } - -migrate_set_downtime --------------------- - -Set maximum tolerated downtime (in seconds) for migrations. - -Arguments: - -- "value": maximum downtime (json-number) - -Example: - --> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } } -<- { "return": {} } - -x-colo-lost-heartbeat --------------------- - -Tell COLO that heartbeat is lost, a failover or takeover is needed. - -Example: - --> { "execute": "x-colo-lost-heartbeat" } -<- { "return": {} } - -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. - -Arguments: - -- "protocol": must be "spice" (json-string) -- "hostname": migration target hostname (json-string) -- "port": spice tcp port for plaintext channels (json-int, optional) -- "tls-port": spice tcp port for tls-secured channels (json-int, optional) -- "cert-subject": server certificate subject (json-string, optional) - -Example: - --> { "execute": "client_migrate_info", - "arguments": { "protocol": "spice", - "hostname": "virt42.lab.kraxel.org", - "port": 1234 } } -<- { "return": {} } - -dump - - -Dump guest memory to file. The file can be processed with crash or gdb. - -Arguments: - -- "paging": do paging to get guest's memory mapping (json-bool) -- "protocol": destination file(started with "file:") or destination file - descriptor (started with "fd:") (json-string) -- "detach": if specified, command will return immediately, without waiting - for the dump to finish. The user can track progress using - "query-dump". (json-bool) -- "begin": the starting physical address. It's optional, and should be specified - with length together (json-int) -- "length": the memory size, in bytes. It's optional, and should be specified - with begin together (json-int) -- "format": the format of guest memory dump. It's optional, and can be - elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will - conflict with paging and filter, ie. begin and length (json-string) - -Example: - --> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } } -<- { "return": {} } - -Notes: - -(1) All boolean arguments default to false - -query-dump-guest-memory-capability ----------- - -Show available formats for 'dump-guest-memory' - -Example: - --> { "execute": "query-dump-guest-memory-capability" } -<- { "return": { "formats": - ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } - -query-dump ----------- - -Query background dump status. - -Arguments: None. - -Example: - --> { "execute": "query-dump" } -<- { "return": { "status": "active", "completed": 1024000, - "total": 2048000 } } - -dump-skeys ----------- - -Save guest storage keys to file. - -Arguments: - -- "filename": file path (json-string) - -Example: - --> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } } -<- { "return": {} } - -netdev_add ----------- - -Add host network device. - -Arguments: - -- "type": the device type, "tap", "user", ... (json-string) -- "id": the device's ID, must be unique (json-string) -- device options - -Example: - --> { "execute": "netdev_add", - "arguments": { "type": "user", "id": "netdev1", - "dnssearch": "example.org" } } -<- { "return": {} } - -Note: The supported device options are the same ones supported by the '-netdev' - command-line argument, which are listed in the '-help' output or QEMU's - manual - -netdev_del ----------- - -Remove host network device. - -Arguments: - -- "id": the device's ID, must be unique (json-string) - -Example: - --> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } -<- { "return": {} } - - -object-add ----------- - -Create QOM object. - -Arguments: - -- "qom-type": the object's QOM type, i.e. the class name (json-string) -- "id": the object's ID, must be unique (json-string) -- "props": a dictionary of object property values (optional, json-dict) - -Example: - --> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1", - "props": { "filename": "/dev/hwrng" } } } -<- { "return": {} } - -object-del ----------- - -Remove QOM object. - -Arguments: - -- "id": the object's ID (json-string) - -Example: - --> { "execute": "object-del", "arguments": { "id": "rng1" } } -<- { "return": {} } - - -block_resize ------------- - -Resize a block image while a guest is running. - -Arguments: - -- "device": the device's ID, must be unique (json-string) -- "node-name": the node name in the block driver state graph (json-string) -- "size": new size - -Example: - --> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } } -<- { "return": {} } - -block-stream ------------- - -Copy data from a backing file into a block device. - -Arguments: - -- "job-id": Identifier for the newly-created block job. If omitted, - the device name will be used. (json-string, optional) -- "device": The device name or node-name of a root node (json-string) -- "base": The file name of the backing image above which copying starts. - It cannot be set if 'base-node' is also set (json-string, optional) -- "base-node": the node name of the backing image above which copying starts. - It cannot be set if 'base' is also set. - (json-string, optional) (Since 2.8) -- "backing-file": The backing file string to write into the active layer. 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. - (json-string, optional) (Since 2.1) -- "speed": the maximum speed, in bytes per second (json-int, optional) -- "on-error": the action to take on an error (default 'report'). 'stop' and - 'enospc' can only be used if the block device supports io-status. - (json-string, optional) (Since 2.1) - -Example: - --> { "execute": "block-stream", "arguments": { "device": "virtio0", - "base": "/tmp/master.qcow2" } } -<- { "return": {} } - -block-commit ------------- - -Live commit of data from overlay image nodes into backing nodes - i.e., writes -data between 'top' and 'base' into 'base'. - -Arguments: - -- "job-id": Identifier for the newly-created block job. If omitted, - the device name will be used. (json-string, optional) -- "device": The device name or node-name of a root node (json-string) -- "base": The file name of the backing image to write data into. - If not specified, this is the deepest backing image - (json-string, optional) -- "top": 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. (json-string, optional) - -- backing-file: 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. - (json-string, optional) (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. - (json-string) -- "speed": the maximum speed, in bytes per second (json-int, optional) - - -Example: - --> { "execute": "block-commit", "arguments": { "device": "virtio0", - "top": "/tmp/snap1.qcow2" } } -<- { "return": {} } - -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. - -Arguments: - -- "job-id": Identifier for the newly-created block job. If omitted, - the device name will be used. (json-string, optional) -- "device": the device name or node-name of a root node which should be copied. - (json-string) -- "target": 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. - (json-string) -- "format": the format of the new destination, default is to probe if 'mode' is - 'existing', else the format of the source - (json-string, optional) -- "sync": what parts of the disk image should be copied to the destination; - possibilities include "full" for all the disk, "top" for only the sectors - allocated in the topmost image, "incremental" for only the dirty sectors in - the bitmap, or "none" to only replicate new I/O (MirrorSyncMode). -- "bitmap": dirty bitmap name for sync==incremental. Must be present if sync - is "incremental", must NOT be present otherwise. -- "mode": whether and how QEMU should create a new image - (NewImageMode, optional, default 'absolute-paths') -- "speed": the maximum speed, in bytes per second (json-int, optional) -- "compress": true to compress data, if the target format supports it. - (json-bool, optional, default false) -- "on-source-error": 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. - (BlockdevOnError, optional) -- "on-target-error": the action to take on an error on the target, default - 'report' (no limitations, since this applies to - a different block device than device). - (BlockdevOnError, optional) - -Example: --> { "execute": "drive-backup", "arguments": { "device": "drive0", - "sync": "full", - "target": "backup.img" } } -<- { "return": {} } - -blockdev-backup ---------------- - -The device version of drive-backup: this command takes an existing named device -as backup target. - -Arguments: - -- "job-id": Identifier for the newly-created block job. If omitted, - the device name will be used. (json-string, optional) -- "device": the device name or node-name of a root node which should be copied. - (json-string) -- "target": the name of the backup target device. (json-string) -- "sync": what parts of the disk image should be copied to the destination; - possibilities include "full" for all the disk, "top" for only the - sectors allocated in the topmost image, or "none" to only replicate - new I/O (MirrorSyncMode). -- "speed": the maximum speed, in bytes per second (json-int, optional) -- "compress": true to compress data, if the target format supports it. - (json-bool, optional, default false) -- "on-source-error": 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. - (BlockdevOnError, optional) -- "on-target-error": the action to take on an error on the target, default - 'report' (no limitations, since this applies to - a different block device than device). - (BlockdevOnError, optional) - -Example: --> { "execute": "blockdev-backup", "arguments": { "device": "src-id", - "sync": "full", - "target": "tgt-id" } } -<- { "return": {} } - -transaction ------------ - -Atomically operate on one or more block devices. Operations that are -currently supported: - - - drive-backup - - blockdev-backup - - blockdev-snapshot-sync - - blockdev-snapshot-internal-sync - - abort - - block-dirty-bitmap-add - - block-dirty-bitmap-clear - -Refer to the qemu/qapi-schema.json file for minimum required QEMU -versions for these operations. A list of dictionaries is accepted, -that contains the actions to be performed. If there is any failure -performing any of the operations, all operations for the group are -abandoned. - -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. - -Arguments: - -actions array: - - "type": the operation to perform (json-string). Possible - values: "drive-backup", "blockdev-backup", - "blockdev-snapshot-sync", - "blockdev-snapshot-internal-sync", - "abort", "block-dirty-bitmap-add", - "block-dirty-bitmap-clear" - - "data": a dictionary. The contents depend on the value - of "type". When "type" is "blockdev-snapshot-sync": - - "device": device name to snapshot (json-string) - - "node-name": graph node name to snapshot (json-string) - - "snapshot-file": name of new image file (json-string) - - "snapshot-node-name": graph node name of the new snapshot (json-string) - - "format": format of new image (json-string, optional) - - "mode": whether and how QEMU should create the snapshot file - (NewImageMode, optional, default "absolute-paths") - When "type" is "blockdev-snapshot-internal-sync": - - "device": the device name or node-name of a root node to snapshot - (json-string) - - "name": name of the new snapshot (json-string) - -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": {} } - -block-dirty-bitmap-add ----------------------- -Since 2.4 - -Create a dirty bitmap with a name on the device, and start tracking the writes. - -Arguments: - -- "node": device/node on which to create dirty bitmap (json-string) -- "name": name of the new dirty bitmap (json-string) -- "granularity": granularity to track writes with (int, optional) - -Example: - --> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0", - "name": "bitmap0" } } -<- { "return": {} } - -block-dirty-bitmap-remove -------------------------- -Since 2.4 - -Stop write tracking and remove the dirty bitmap that was created with -block-dirty-bitmap-add. - -Arguments: - -- "node": device/node on which to remove dirty bitmap (json-string) -- "name": name of the dirty bitmap to remove (json-string) - -Example: - --> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0", - "name": "bitmap0" } } -<- { "return": {} } - -block-dirty-bitmap-clear ------------------------- -Since 2.4 - -Reset the dirty bitmap associated with a node so that an incremental backup -from this point in time forward will only backup clusters modified after this -clear operation. - -Arguments: - -- "node": device/node on which to remove dirty bitmap (json-string) -- "name": name of the dirty bitmap to remove (json-string) - -Example: - --> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0", - "name": "bitmap0" } } -<- { "return": {} } - -blockdev-snapshot-sync ----------------------- - -Synchronous snapshot of a block device. snapshot-file specifies 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. If does not -exist, a new file will be created. format specifies the format of the -snapshot image, default is qcow2. - -Arguments: - -- "device": device name to snapshot (json-string) -- "node-name": graph node name to snapshot (json-string) -- "snapshot-file": name of new image file (json-string) -- "snapshot-node-name": graph node name of the new snapshot (json-string) -- "mode": whether and how QEMU should create the snapshot file - (NewImageMode, optional, default "absolute-paths") -- "format": format of new image (json-string, optional) - -Example: - --> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0", - "snapshot-file": - "/some/place/my-image", - "format": "qcow2" } } -<- { "return": {} } - -blockdev-snapshot ------------------ -Since 2.5 - -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. - -Arguments: - -- "node": device that will have a snapshot created (json-string) -- "overlay": device that will have 'node' as its backing image (json-string) - -Example: - --> { "execute": "blockdev-add", - "arguments": { "driver": "qcow2", - "node-name": "node1534", - "file": { "driver": "file", - "filename": "hd1.qcow2" }, - "backing": "" } } - -<- { "return": {} } - --> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0", - "overlay": "node1534" } } -<- { "return": {} } - -blockdev-snapshot-internal-sync -------------------------------- - -Synchronously take an internal snapshot of a block device when the format of -image used supports it. If the name is an empty string, or a snapshot with -name already exists, the operation will fail. - -Arguments: - -- "device": the device name or node-name of a root node to snapshot - (json-string) -- "name": name of the new snapshot (json-string) - -Example: - --> { "execute": "blockdev-snapshot-internal-sync", - "arguments": { "device": "ide-hd0", - "name": "snapshot0" } - } -<- { "return": {} } - -blockdev-snapshot-delete-internal-sync --------------------------------------- - -Synchronously delete an internal snapshot of a block device when the format of -image used supports it. The snapshot is identified by name or id or both. One -of name or id is required. If the snapshot is not found, the operation will -fail. - -Arguments: - -- "device": the device name or node-name of a root node (json-string) -- "id": ID of the snapshot (json-string, optional) -- "name": name of the snapshot (json-string, optional) - -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 - } - } - -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. - -Arguments: - -- "job-id": Identifier for the newly-created block job. If omitted, - the device name will be used. (json-string, optional) -- "device": the device name or node-name of a root node whose writes should be - mirrored. (json-string) -- "target": name of new image file (json-string) -- "format": format of new image (json-string, optional) -- "node-name": the name of the new block driver state in the node graph - (json-string, optional) -- "replaces": the block driver node name to replace when finished - (json-string, optional) -- "mode": how an image file should be created into the target - file/device (NewImageMode, optional, default 'absolute-paths') -- "speed": maximum speed of the streaming job, in bytes per second - (json-int) -- "granularity": granularity of the dirty bitmap, in bytes (json-int, optional) -- "buf-size": maximum amount of data in flight from source to target, in bytes - (json-int, default 10M) -- "sync": what parts of the disk image should be copied to the destination; - possibilities include "full" for all the disk, "top" for only the sectors - allocated in the topmost image, or "none" to only replicate new I/O - (MirrorSyncMode). -- "on-source-error": the action to take on an error on the source - (BlockdevOnError, default 'report') -- "on-target-error": the action to take on an error on the target - (BlockdevOnError, default 'report') -- "unmap": whether the target sectors should be discarded where source has only - zeroes. (json-bool, optional, default true) - -The default value of the granularity is the image cluster size clamped -between 4096 and 65536, if the image format defines one. If the format -does not define a cluster size, the default value of the granularity -is 65536. - - -Example: - --> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0", - "target": "/some/place/my-image", - "sync": "full", - "format": "qcow2" } } -<- { "return": {} } - -blockdev-mirror ------------- - -Start mirroring a block device's writes to another block device. target -specifies the target of mirror operation. - -Arguments: - -- "job-id": Identifier for the newly-created block job. If omitted, - the device name will be used. (json-string, optional) -- "device": The device name or node-name of a root node whose writes should be - mirrored (json-string) -- "target": device name to mirror to (json-string) -- "replaces": the block driver node name to replace when finished - (json-string, optional) -- "speed": maximum speed of the streaming job, in bytes per second - (json-int) -- "granularity": granularity of the dirty bitmap, in bytes (json-int, optional) -- "buf_size": maximum amount of data in flight from source to target, in bytes - (json-int, default 10M) -- "sync": what parts of the disk image should be copied to the destination; - possibilities include "full" for all the disk, "top" for only the sectors - allocated in the topmost image, or "none" to only replicate new I/O - (MirrorSyncMode). -- "on-source-error": the action to take on an error on the source - (BlockdevOnError, default 'report') -- "on-target-error": the action to take on an error on the target - (BlockdevOnError, default 'report') - -The default value of the granularity is the image cluster size clamped -between 4096 and 65536, if the image format defines one. If the format -does not define a cluster size, the default value of the granularity -is 65536. - -Example: - --> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0", - "target": "target0", - "sync": "full" } } -<- { "return": {} } - -change-backing-file -------------------- -Since: 2.1 - -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. - -Arguments: - -- "image-node-name": The name of the block driver state node of the - image to modify. The "device" is argument is used to - verify "image-node-name" is in the chain described by - "device". - (json-string, optional) - -- "device": The device name or node-name of the root node that owns - image-node-name. - (json-string) - -- "backing-file": 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. - (json-string) - -Returns: Nothing on success - If "device" does not exist or cannot be determined, DeviceNotFound - -balloon -------- - -Request VM to change its memory allocation (in bytes). - -Arguments: - -- "value": New memory allocation (json-int) - -Example: - --> { "execute": "balloon", "arguments": { "value": 536870912 } } -<- { "return": {} } - -set_link --------- - -Change the link status of a network adapter. - -Arguments: - -- "name": network device name (json-string) -- "up": status is up (json-bool) - -Example: - --> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } } -<- { "return": {} } - -getfd ------ - -Receive a file descriptor via SCM rights and assign it a name. - -Arguments: - -- "fdname": file descriptor name (json-string) - -Example: - --> { "execute": "getfd", "arguments": { "fdname": "fd1" } } -<- { "return": {} } - -Notes: - -(1) If the name specified by the "fdname" argument already exists, - the file descriptor assigned to it will be closed and replaced - by the received file descriptor. -(2) The 'closefd' command can be used to explicitly close the file - descriptor when it is no longer needed. - -closefd -------- - -Close a file descriptor previously passed via SCM rights. - -Arguments: - -- "fdname": file descriptor name (json-string) - -Example: - --> { "execute": "closefd", "arguments": { "fdname": "fd1" } } -<- { "return": {} } - -add-fd -------- - -Add a file descriptor, that was passed via SCM rights, to an fd set. - -Arguments: - -- "fdset-id": The ID of the fd set to add the file descriptor to. - (json-int, optional) -- "opaque": A free-form string that can be used to describe the fd. - (json-string, optional) - -Return a json-object with the following information: - -- "fdset-id": The ID of the fd set that the fd was added to. (json-int) -- "fd": The file descriptor that was received via SCM rights and added to the - fd set. (json-int) - -Example: - --> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } -<- { "return": { "fdset-id": 1, "fd": 3 } } - -Notes: - -(1) The list of fd sets is shared by all monitor connections. -(2) If "fdset-id" is not specified, a new fd set will be created. - -remove-fd ---------- - -Remove a file descriptor from an fd set. - -Arguments: - -- "fdset-id": The ID of the fd set that the file descriptor belongs to. - (json-int) -- "fd": The file descriptor that is to be removed. (json-int, optional) - -Example: - --> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } -<- { "return": {} } - -Notes: - -(1) The list of fd sets is shared by all monitor connections. -(2) If "fd" is not specified, all file descriptors in "fdset-id" will be - removed. - -query-fdsets -------------- - -Return information describing all fd sets. - -Arguments: None - -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 - } - ] - } - -Note: The list of fd sets is shared by all monitor connections. - -block_passwd ------------- - -Set the password of encrypted block devices. - -Arguments: - -- "device": device name (json-string) -- "node-name": name in the block driver state graph (json-string) -- "password": password (json-string) - -Example: - --> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0", - "password": "12345" } } -<- { "return": {} } - -block_set_io_throttle ------------- - -Change I/O throttle limits for a block drive. - -Arguments: - -- "device": block device name (deprecated, use @id instead) - (json-string, optional) -- "id": the name or QOM path of the guest device (json-string, optional) -- "bps": total throughput limit in bytes per second (json-int) -- "bps_rd": read throughput limit in bytes per second (json-int) -- "bps_wr": write throughput limit in bytes per second (json-int) -- "iops": total I/O operations per second (json-int) -- "iops_rd": read I/O operations per second (json-int) -- "iops_wr": write I/O operations per second (json-int) -- "bps_max": total throughput limit during bursts, in bytes (json-int, optional) -- "bps_rd_max": read throughput limit during bursts, in bytes (json-int, optional) -- "bps_wr_max": write throughput limit during bursts, in bytes (json-int, optional) -- "iops_max": total I/O operations per second during bursts (json-int, optional) -- "iops_rd_max": read I/O operations per second during bursts (json-int, optional) -- "iops_wr_max": write I/O operations per second during bursts (json-int, optional) -- "bps_max_length": maximum length of the @bps_max burst period, in seconds (json-int, optional) -- "bps_rd_max_length": maximum length of the @bps_rd_max burst period, in seconds (json-int, optional) -- "bps_wr_max_length": maximum length of the @bps_wr_max burst period, in seconds (json-int, optional) -- "iops_max_length": maximum length of the @iops_max burst period, in seconds (json-int, optional) -- "iops_rd_max_length": maximum length of the @iops_rd_max burst period, in seconds (json-int, optional) -- "iops_wr_max_length": maximum length of the @iops_wr_max burst period, in seconds (json-int, optional) -- "iops_size": I/O size in bytes when limiting (json-int, optional) -- "group": throttle group name (json-string, optional) - -Example: - --> { "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": {} } - -set_password ------------- - -Set the password for vnc/spice protocols. - -Arguments: - -- "protocol": protocol name (json-string) -- "password": password (json-string) -- "connected": [ keep | disconnect | fail ] (json-string, optional) - -Example: - --> { "execute": "set_password", "arguments": { "protocol": "vnc", - "password": "secret" } } -<- { "return": {} } - -expire_password ---------------- - -Set the password expire time for vnc/spice protocols. - -Arguments: - -- "protocol": protocol name (json-string) -- "time": [ now | never | +secs | secs ] (json-string) - -Example: - --> { "execute": "expire_password", "arguments": { "protocol": "vnc", - "time": "+60" } } -<- { "return": {} } - -add_client ----------- - -Add a graphics client - -Arguments: - -- "protocol": protocol name (json-string) -- "fdname": file descriptor name (json-string) -- "skipauth": whether to skip authentication (json-bool, optional) -- "tls": whether to perform TLS (json-bool, optional) - -Example: - --> { "execute": "add_client", "arguments": { "protocol": "vnc", - "fdname": "myclient" } } -<- { "return": {} } - -qmp_capabilities ----------------- - -Enable QMP capabilities. - -Arguments: None. - -Example: - --> { "execute": "qmp_capabilities" } -<- { "return": {} } - -Note: This command must be issued before issuing any other command. - -human-monitor-command ---------------------- - -Execute a Human Monitor command. - -Arguments: - -- command-line: the command name and its arguments, just like the - Human Monitor's shell (json-string) -- cpu-index: select the CPU number to be used by commands which access CPU - data, like 'info registers'. The Monitor selects CPU 0 if this - argument is not provided (json-int, optional) - -Example: - --> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } } -<- { "return": "kvm support: enabled\r\n" } - -Notes: - -(1) The Human Monitor is NOT an stable interface, 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 - -(2) Limitations: - - o This command is stateless, this means that commands that depend - on state information (such as getfd) might not work - - o Commands that prompt the user for data (eg. 'cont' when the block - device is encrypted) don't currently work - -3. Query Commands -================= - - -query-version -------------- - -Show QEMU version. - -Return a json-object with the following information: - -- "qemu": A json-object containing three integer values: - - "major": QEMU's major version (json-int) - - "minor": QEMU's minor version (json-int) - - "micro": QEMU's micro version (json-int) -- "package": package's version (json-string) - -Example: - --> { "execute": "query-version" } -<- { - "return":{ - "qemu":{ - "major":0, - "minor":11, - "micro":5 - }, - "package":"" - } - } - -query-commands --------------- - -List QMP available commands. - -Each command is represented by a json-object, the returned value is a json-array -of all commands. - -Each json-object contain: - -- "name": command's name (json-string) - -Example: - --> { "execute": "query-commands" } -<- { - "return":[ - { - "name":"query-balloon" - }, - { - "name":"system_powerdown" - } - ] - } - -Note: This example has been shortened as the real response is too long. - -query-events --------------- - -List QMP available events. - -Each event is represented by a json-object, the returned value is a json-array -of all events. - -Each json-object contains: - -- "name": event's name (json-string) - -Example: - --> { "execute": "query-events" } -<- { - "return":[ - { - "name":"SHUTDOWN" - }, - { - "name":"RESET" - } - ] - } - -Note: This example has been shortened as the real response is too long. - -query-qmp-schema ----------------- - -Return the QMP wire schema. The returned value is a json-array of -named schema entities. Entities are commands, events and various -types. See docs/qapi-code-gen.txt for information on their structure -and intended use. - -query-chardev -------------- - -Each device is represented by a json-object. The returned value is a json-array -of all devices. - -Each json-object contain the following: - -- "label": device's label (json-string) -- "filename": device's file (json-string) -- "frontend-open": open/closed state of the frontend device attached to this - backend (json-bool) - -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 - } - ] - } - -query-chardev-backends -------------- - -List available character device backends. - -Each backend is represented by a json-object, the returned value is a json-array -of all backends. - -Each json-object contains: - -- "name": backend name (json-string) - -Example: - --> { "execute": "query-chardev-backends" } -<- { - "return":[ - { - "name":"udp" - }, - { - "name":"tcp" - }, - { - "name":"unix" - }, - { - "name":"spiceport" - } - ] - } - -query-block ------------ - -Show the block devices. - -Each block device information is stored in a json-object and the returned value -is a json-array of all devices. - -Each json-object contain the following: - -- "device": device name (json-string) -- "type": device type (json-string) - - deprecated, retained for backward compatibility - - Possible values: "unknown" -- "removable": true if the device is removable, false otherwise (json-bool) -- "locked": true if the device is locked, false otherwise (json-bool) -- "tray_open": only present if removable, true if the device has a tray, - and it is open (json-bool) -- "inserted": only present if the device is inserted, it is a json-object - containing the following: - - "file": device file name (json-string) - - "ro": true if read-only, false otherwise (json-bool) - - "drv": driver format name (json-string) - - Possible values: "blkdebug", "bochs", "cloop", "dmg", - "file", "file", "ftp", "ftps", "host_cdrom", - "host_device", "http", "https", - "nbd", "parallels", "qcow", "qcow2", "raw", - "vdi", "vmdk", "vpc", "vvfat" - - "backing_file": backing file name (json-string, optional) - - "backing_file_depth": number of files in the backing file chain (json-int) - - "encrypted": true if encrypted, false otherwise (json-bool) - - "bps": limit total bytes per second (json-int) - - "bps_rd": limit read bytes per second (json-int) - - "bps_wr": limit write bytes per second (json-int) - - "iops": limit total I/O operations per second (json-int) - - "iops_rd": limit read operations per second (json-int) - - "iops_wr": limit write operations per second (json-int) - - "bps_max": total max in bytes (json-int) - - "bps_rd_max": read max in bytes (json-int) - - "bps_wr_max": write max in bytes (json-int) - - "iops_max": total I/O operations max (json-int) - - "iops_rd_max": read I/O operations max (json-int) - - "iops_wr_max": write I/O operations max (json-int) - - "iops_size": I/O size when limiting by iops (json-int) - - "detect_zeroes": detect and optimize zero writing (json-string) - - Possible values: "off", "on", "unmap" - - "write_threshold": write offset threshold in bytes, a event will be - emitted if crossed. Zero if disabled (json-int) - - "image": the detail of the image, it is a json-object containing - the following: - - "filename": image file name (json-string) - - "format": image format (json-string) - - "virtual-size": image capacity in bytes (json-int) - - "dirty-flag": true if image is not cleanly closed, not present - means clean (json-bool, optional) - - "actual-size": actual size on disk in bytes of the image, not - present when image does not support thin - provision (json-int, optional) - - "cluster-size": size of a cluster in bytes, not present if image - format does not support it (json-int, optional) - - "encrypted": true if the image is encrypted, not present means - false or the image format does not support - encryption (json-bool, optional) - - "backing_file": backing file name, not present means no backing - file is used or the image format does not - support backing file chain - (json-string, optional) - - "full-backing-filename": full path of the backing file, not - present if it equals backing_file or no - backing file is used - (json-string, optional) - - "backing-filename-format": the format of the backing file, not - present means unknown or no backing - file (json-string, optional) - - "snapshots": the internal snapshot info, it is an optional list - of json-object containing the following: - - "id": unique snapshot id (json-string) - - "name": snapshot name (json-string) - - "vm-state-size": size of the VM state in bytes (json-int) - - "date-sec": UTC date of the snapshot in seconds (json-int) - - "date-nsec": fractional part in nanoseconds to be used with - date-sec (json-int) - - "vm-clock-sec": VM clock relative to boot in seconds - (json-int) - - "vm-clock-nsec": fractional part in nanoseconds to be used - with vm-clock-sec (json-int) - - "backing-image": the detail of the backing image, it is an - optional json-object only present when a - backing image present for this image - -- "io-status": I/O operation status, only present if the device supports it - and the VM is configured to stop on errors. It's always reset - to "ok" when the "cont" command is issued (json_string, optional) - - Possible values: "ok", "failed", "nospace" - -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 - } - } - }, - "type":"unknown" - }, - { - "io-status": "ok", - "device":"ide1-cd0", - "locked":false, - "removable":true, - "type":"unknown" - }, - { - "device":"floppy0", - "locked":false, - "removable":true, - "type":"unknown" - }, - { - "device":"sd0", - "locked":false, - "removable":true, - "type":"unknown" - } - ] - } - -query-blockstats ----------------- - -Show block device statistics. - -Each device statistic information is stored in a json-object and the returned -value is a json-array of all devices. - -Each json-object contain the following: - -- "device": device name (json-string) -- "stats": A json-object with the statistics information, it contains: - - "rd_bytes": bytes read (json-int) - - "wr_bytes": bytes written (json-int) - - "rd_operations": read operations (json-int) - - "wr_operations": write operations (json-int) - - "flush_operations": cache flush operations (json-int) - - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int) - - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int) - - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int) - - "wr_highest_offset": The offset after the greatest byte written to the - BlockDriverState since it has been opened (json-int) - - "rd_merged": number of read requests that have been merged into - another request (json-int) - - "wr_merged": number of write requests that have been merged into - another request (json-int) - - "idle_time_ns": time since the last I/O operation, in - nanoseconds. If the field is absent it means - that there haven't been any operations yet - (json-int, optional) - - "failed_rd_operations": number of failed read operations - (json-int) - - "failed_wr_operations": number of failed write operations - (json-int) - - "failed_flush_operations": number of failed flush operations - (json-int) - - "invalid_rd_operations": number of invalid read operations - (json-int) - - "invalid_wr_operations": number of invalid write operations - (json-int) - - "invalid_flush_operations": number of invalid flush operations - (json-int) - - "account_invalid": whether invalid operations are included in - the last access statistics (json-bool) - - "account_failed": whether failed operations are included in the - latency and last access statistics - (json-bool) - - "timed_stats": A json-array containing statistics collected in - specific intervals, with the following members: - - "interval_length": interval used for calculating the - statistics, in seconds (json-int) - - "min_rd_latency_ns": minimum latency of read operations in - the defined interval, in nanoseconds - (json-int) - - "min_wr_latency_ns": minimum latency of write operations in - the defined interval, in nanoseconds - (json-int) - - "min_flush_latency_ns": minimum latency of flush operations - in the defined interval, in - nanoseconds (json-int) - - "max_rd_latency_ns": maximum latency of read operations in - the defined interval, in nanoseconds - (json-int) - - "max_wr_latency_ns": maximum latency of write operations in - the defined interval, in nanoseconds - (json-int) - - "max_flush_latency_ns": maximum latency of flush operations - in the defined interval, in - nanoseconds (json-int) - - "avg_rd_latency_ns": average latency of read operations in - the defined interval, in nanoseconds - (json-int) - - "avg_wr_latency_ns": average latency of write operations in - the defined interval, in nanoseconds - (json-int) - - "avg_flush_latency_ns": average latency of flush operations - in the defined interval, in - nanoseconds (json-int) - - "avg_rd_queue_depth": average number of pending read - operations in the defined interval - (json-number) - - "avg_wr_queue_depth": average number of pending write - operations in the defined interval - (json-number). -- "parent": 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 - (json-object, optional) - -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 - } - } - ] - } - -query-cpus ----------- - -Show CPU information. - -Return a json-array. Each CPU is represented by a json-object, which contains: - -- "CPU": CPU index (json-int) -- "current": true if this is the current CPU, false otherwise (json-bool) -- "halted": true if the cpu is halted, false otherwise (json-bool) -- "qom_path": path to the CPU object in the QOM tree (json-str) -- "arch": architecture of the cpu, which determines what additional - keys will be present (json-str) -- Current program counter. The key's name depends on the architecture: - "pc": i386/x86_64 (json-int) - "nip": PPC (json-int) - "pc" and "npc": sparc (json-int) - "PC": mips (json-int) -- "thread_id": ID of the underlying host thread (json-int) - -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 - } - ] - } - -query-iothreads ---------------- - -Returns a list of information about each iothread. - -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. - -Return a json-array. Each iothread is represented by a json-object, which contains: - -- "id": name of iothread (json-str) -- "thread-id": ID of the underlying host thread (json-int) - -Example: - --> { "execute": "query-iothreads" } -<- { - "return":[ - { - "id":"iothread0", - "thread-id":3134 - }, - { - "id":"iothread1", - "thread-id":3135 - } - ] - } - -query-pci ---------- - -PCI buses and devices information. - -The returned value is a json-array of all buses. 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. - -The bus json-object contains the following: - -- "bus": bus number (json-int) -- "devices": a json-array of json-objects, each json-object represents a - PCI device - -The PCI device json-object contains the following: - -- "bus": identical to the parent's bus number (json-int) -- "slot": slot number (json-int) -- "function": function number (json-int) -- "class_info": a json-object containing: - - "desc": device class description (json-string, optional) - - "class": device class number (json-int) -- "id": a json-object containing: - - "device": device ID (json-int) - - "vendor": vendor ID (json-int) -- "irq": device's IRQ if assigned (json-int, optional) -- "qdev_id": qdev id string (json-string) -- "pci_bridge": It's a json-object, only present if this device is a - PCI bridge, contains: - - "bus": bus number (json-int) - - "secondary": secondary bus number (json-int) - - "subordinate": subordinate bus number (json-int) - - "io_range": I/O memory range information, a json-object with the - following members: - - "base": base address, in bytes (json-int) - - "limit": limit address, in bytes (json-int) - - "memory_range": memory range information, a json-object with the - following members: - - "base": base address, in bytes (json-int) - - "limit": limit address, in bytes (json-int) - - "prefetchable_range": Prefetchable memory range information, a - json-object with the following members: - - "base": base address, in bytes (json-int) - - "limit": limit address, in bytes (json-int) - - "devices": a json-array of PCI devices if there's any attached, each - each element is represented by a json-object, which contains - the same members of the 'PCI device json-object' described - above (optional) -- "regions": a json-array of json-objects, each json-object represents a - memory region of this device - -The memory range json-object contains the following: - -- "base": base memory address (json-int) -- "limit": limit value (json-int) - -The region json-object can be an I/O region or a memory region, an I/O region -json-object contains the following: - -- "type": "io" (json-string, fixed) -- "bar": BAR number (json-int) -- "address": memory address (json-int) -- "size": memory size (json-int) - -A memory region json-object contains the following: - -- "type": "memory" (json-string, fixed) -- "bar": BAR number (json-int) -- "address": memory address (json-int) -- "size": memory size (json-int) -- "mem_type_64": true or false (json-bool) -- "prefetch": true or false (json-bool) - -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" - } - ] - } - ] - } - ] - } - -Note: This example has been shortened as the real response is too long. - -query-kvm ---------- - -Show KVM information. - -Return a json-object with the following information: - -- "enabled": true if KVM support is enabled, false otherwise (json-bool) -- "present": true if QEMU has KVM support, false otherwise (json-bool) - -Example: - --> { "execute": "query-kvm" } -<- { "return": { "enabled": true, "present": true } } - -query-status ------------- - -Return a json-object with the following information: - -- "running": true if the VM is running, or false if it is paused (json-bool) -- "singlestep": true if the VM is in single step mode, - false otherwise (json-bool) -- "status": one of the following values (json-string) - "debug" - QEMU is running on a debugger - "inmigrate" - guest is paused waiting for an incoming migration - "internal-error" - An internal error that prevents further guest - execution has occurred - "io-error" - the last IOP has failed and the device is configured - to pause on I/O errors - "paused" - guest has been paused via the 'stop' command - "postmigrate" - guest is paused following a successful 'migrate' - "prelaunch" - QEMU was started with -S and guest has not started - "finish-migrate" - guest is paused to finish the migration process - "restore-vm" - guest is paused to restore VM state - "running" - guest is actively running - "save-vm" - guest is paused to save the VM state - "shutdown" - guest is shut down (and -no-shutdown is in use) - "watchdog" - the watchdog action is configured to pause and - has been triggered - -Example: - --> { "execute": "query-status" } -<- { "return": { "running": true, "singlestep": false, "status": "running" } } - -query-mice ----------- - -Show VM mice information. - -Each mouse is represented by a json-object, the returned value is a json-array -of all mice. - -The mouse json-object contains the following: - -- "name": mouse's name (json-string) -- "index": mouse's index (json-int) -- "current": true if this mouse is receiving events, false otherwise (json-bool) -- "absolute": true if the mouse generates absolute input events (json-bool) - -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 - } - ] - } - -query-vnc ---------- - -Show VNC server information. - -Return a json-object with server information. Connected clients are returned -as a json-array of json-objects. - -The main json-object contains the following: - -- "enabled": true or false (json-bool) -- "host": server's IP address (json-string) -- "family": address family (json-string) - - Possible values: "ipv4", "ipv6", "unix", "unknown" -- "service": server's port number (json-string) -- "auth": authentication method (json-string) - - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight", - "tls", "ultra", "unknown", "vencrypt", "vencrypt", - "vencrypt+plain", "vencrypt+tls+none", - "vencrypt+tls+plain", "vencrypt+tls+sasl", - "vencrypt+tls+vnc", "vencrypt+x509+none", - "vencrypt+x509+plain", "vencrypt+x509+sasl", - "vencrypt+x509+vnc", "vnc" -- "clients": a json-array of all connected clients - -Clients are described by a json-object, each one contain the following: - -- "host": client's IP address (json-string) -- "family": address family (json-string) - - Possible values: "ipv4", "ipv6", "unix", "unknown" -- "service": client's port number (json-string) -- "x509_dname": TLS dname (json-string, optional) -- "sasl_username": SASL username (json-string, optional) - -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" - } - ] - } - } - -query-spice ------------ - -Show SPICE server information. - -Return a json-object with server information. Connected clients are returned -as a json-array of json-objects. - -The main json-object contains the following: - -- "enabled": true or false (json-bool) -- "host": server's IP address (json-string) -- "port": server's port number (json-int, optional) -- "tls-port": server's port number (json-int, optional) -- "auth": authentication method (json-string) - - Possible values: "none", "spice" -- "channels": a json-array of all active channels clients - -Channels are described by a json-object, each one contain the following: - -- "host": client's IP address (json-string) -- "family": address family (json-string) - - Possible values: "ipv4", "ipv6", "unix", "unknown" -- "port": client's port number (json-string) -- "connection-id": spice connection id. All channels with the same id - belong to the same spice session (json-int) -- "channel-type": channel type. "1" is the main control channel, filter for - this one if you want track spice sessions only (json-int) -- "channel-id": channel id. Usually "0", might be different needed when - multiple channels of the same type exist, such as multiple - display channels in a multihead setup (json-int) -- "tls": whether the channel is encrypted (json-bool) - -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 ... ] - ] - } - } - -query-name ----------- - -Show VM name. - -Return a json-object with the following information: - -- "name": VM's name (json-string, optional) - -Example: - --> { "execute": "query-name" } -<- { "return": { "name": "qemu-name" } } - -query-uuid ----------- - -Show VM UUID. - -Return a json-object with the following information: - -- "UUID": Universally Unique Identifier (json-string) - -Example: - --> { "execute": "query-uuid" } -<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } - -query-command-line-options --------------------------- - -Show command line option schema. - -Return a json-array of command line option schema for all options (or for -the given option), returning an error if the given option doesn't exist. - -Each array entry contains the following: - -- "option": option name (json-string) -- "parameters": a json-array describes all parameters of the option: - - "name": parameter name (json-string) - - "type": parameter type (one of 'string', 'boolean', 'number', - or 'size') - - "help": human readable description of the parameter - (json-string, optional) - - "default": default value string for the parameter - (json-string, optional) - -Example: - --> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } } -<- { "return": [ - { - "parameters": [ - { - "name": "romfile", - "type": "string" - }, - { - "name": "bootindex", - "type": "number" - } - ], - "option": "option-rom" - } - ] - } - -query-migrate -------------- - -Migration status. - -Return a json-object. 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. - -The main json-object contains the following: - -- "status": migration status (json-string) - - Possible values: "setup", "active", "completed", "failed", "cancelled" -- "total-time": total amount of ms since migration started. If - migration has ended, it returns the total migration - time (json-int) -- "setup-time" amount of setup time in milliseconds _before_ the - iterations begin but _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. (json-int) -- "downtime": only present when migration has finished correctly - total amount in ms for downtime that happened (json-int) -- "expected-downtime": only present while migration is active - total amount in ms for downtime that was calculated on - the last bitmap round (json-int) -- "ram": only present if "status" is "active", it is a json-object with the - following RAM information: - - "transferred": amount transferred in bytes (json-int) - - "remaining": amount remaining to transfer in bytes (json-int) - - "total": total amount of memory in bytes (json-int) - - "duplicate": number of pages filled entirely with the same - byte (json-int) - These are sent over the wire much more efficiently. - - "skipped": number of skipped zero pages (json-int) - - "normal" : number of whole pages transferred. I.e. they - were not sent as duplicate or xbzrle pages (json-int) - - "normal-bytes" : number of bytes transferred in whole - pages. This is just normal pages times size of one page, - but this way upper levels don't need to care about page - size (json-int) - - "dirty-sync-count": times that dirty ram was synchronized (json-int) -- "disk": only present if "status" is "active" and it is a block migration, - it is a json-object with the following disk information: - - "transferred": amount transferred in bytes (json-int) - - "remaining": amount remaining to transfer in bytes json-int) - - "total": total disk size in bytes (json-int) -- "xbzrle-cache": only present if XBZRLE is active. - It is a json-object with the following XBZRLE information: - - "cache-size": XBZRLE cache size in bytes - - "bytes": number of bytes transferred for XBZRLE compressed pages - - "pages": number of XBZRLE compressed pages - - "cache-miss": number of XBRZRLE page cache misses - - "cache-miss-rate": rate of XBRZRLE page cache misses - - "overflow": number of times XBZRLE overflows. This means - that the XBZRLE encoding was bigger than just sent the - whole page, and then we sent the whole page instead (as as - normal page). - -Examples: - -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 - } - } - } - -migrate-set-capabilities ------------------------- - -Enable/Disable migration capabilities - -- "xbzrle": XBZRLE support -- "rdma-pin-all": pin all pages when using RDMA during migration -- "auto-converge": throttle down guest to help convergence of migration -- "zero-blocks": compress zero blocks during block migration -- "compress": use multiple compression threads to accelerate live migration -- "events": generate events for each migration state change -- "postcopy-ram": postcopy mode for live migration -- "x-colo": COarse-Grain LOck Stepping (COLO) for Non-stop Service - -Arguments: - -Example: - --> { "execute": "migrate-set-capabilities" , "arguments": - { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } - -query-migrate-capabilities --------------------------- - -Query current migration capabilities - -- "capabilities": migration capabilities state - - "xbzrle" : XBZRLE state (json-bool) - - "rdma-pin-all" : RDMA Pin Page state (json-bool) - - "auto-converge" : Auto Converge state (json-bool) - - "zero-blocks" : Zero Blocks state (json-bool) - - "compress": Multiple compression threads state (json-bool) - - "events": Migration state change event state (json-bool) - - "postcopy-ram": postcopy ram state (json-bool) - - "x-colo": COarse-Grain LOck Stepping for Non-stop Service (json-bool) - -Arguments: - -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"} - ]} - -migrate-set-parameters ----------------------- - -Set migration parameters - -- "compress-level": set compression level during migration (json-int) -- "compress-threads": set compression thread count for migration (json-int) -- "decompress-threads": set decompression thread count for migration (json-int) -- "cpu-throttle-initial": set initial percentage of time guest cpus are - throttled for auto-converge (json-int) -- "cpu-throttle-increment": set throttle increasing percentage for - auto-converge (json-int) -- "max-bandwidth": set maximum speed for migrations (in bytes/sec) (json-int) -- "downtime-limit": set maximum tolerated downtime (in milliseconds) for - migrations (json-int) -- "x-checkpoint-delay": set the delay time for periodic checkpoint (json-int) - -Arguments: - -Example: - --> { "execute": "migrate-set-parameters" , "arguments": - { "compress-level": 1 } } - -query-migrate-parameters ------------------------- - -Query current migration parameters - -- "parameters": migration parameters value - - "compress-level" : compression level value (json-int) - - "compress-threads" : compression thread count value (json-int) - - "decompress-threads" : decompression thread count value (json-int) - - "cpu-throttle-initial" : initial percentage of time guest cpus are - throttled (json-int) - - "cpu-throttle-increment" : throttle increasing percentage for - auto-converge (json-int) - - "max-bandwidth" : maximium migration speed in bytes per second - (json-int) - - "downtime-limit" : maximum tolerated downtime of migration in - milliseconds (json-int) -Arguments: - -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 - } - } - -query-balloon -------------- - -Show balloon information. - -Make an asynchronous request for balloon info. When the request completes a -json-object will be returned containing the following data: - -- "actual": current balloon value in bytes (json-int) - -Example: - --> { "execute": "query-balloon" } -<- { - "return":{ - "actual":1073741824, - } - } - -query-tpm ---------- - -Return information about the TPM device. - -Arguments: None - -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" - } - ] - } - -query-tpm-models ----------------- - -Return a list of supported TPM models. - -Arguments: None - -Example: - --> { "execute": "query-tpm-models" } -<- { "return": [ "tpm-tis" ] } - -query-tpm-types ---------------- - -Return a list of supported TPM types. - -Arguments: None - -Example: - --> { "execute": "query-tpm-types" } -<- { "return": [ "passthrough" ] } - -chardev-add ----------------- - -Add a chardev. - -Arguments: - -- "id": the chardev's ID, must be unique (json-string) -- "backend": chardev backend type + parameters - -Examples: - --> { "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" } } - -chardev-remove --------------- - -Remove a chardev. - -Arguments: - -- "id": the chardev's ID, must exist and not be in use (json-string) - -Example: - --> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } -<- { "return": {} } - -query-rx-filter ---------------- - -Show rx-filter information. - -Returns a json-array of rx-filter information for all NICs (or for the -given NIC), returning an error if the given NIC doesn't exist, or -given NIC doesn't support rx-filter querying, or given net client -isn't a NIC. - -The query will clear the event notification flag of each NIC, then qemu -will start to emit event to QMP monitor. - -Each array entry contains the following: - -- "name": net client name (json-string) -- "promiscuous": promiscuous mode is enabled (json-bool) -- "multicast": multicast receive state (one of 'normal', 'none', 'all') -- "unicast": unicast receive state (one of 'normal', 'none', 'all') -- "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0) -- "broadcast-allowed": allow to receive broadcast (json-bool) -- "multicast-overflow": multicast table is overflowed (json-bool) -- "unicast-overflow": unicast table is overflowed (json-bool) -- "main-mac": main macaddr string (json-string) -- "vlan-table": a json-array of active vlan id -- "unicast-table": a json-array of unicast macaddr string -- "multicast-table": a json-array of multicast macaddr string - -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 - } - ] - } - -blockdev-add ------------- - -Add a block device. - -This command is still a work in progress. It doesn't support all -block drivers among other things. Stay away from it unless you want -to help with its development. - -For the arguments, see the QAPI schema documentation of BlockdevOptions. - -Example (1): - --> { "execute": "blockdev-add", - "arguments": { "driver": "qcow2", - "file": { "driver": "file", - "filename": "test.qcow2" } } } -<- { "return": {} } - -Example (2): - --> { "execute": "blockdev-add", - "arguments": { - "driver": "qcow2", - "node-name": "my_disk", - "discard": "unmap", - "cache": { - "direct": true, - "writeback": true - }, - "file": { - "driver": "file", - "filename": "/tmp/test.qcow2" - }, - "backing": { - "driver": "raw", - "file": { - "driver": "file", - "filename": "/dev/fdset/4" - } - } - } - } - -<- { "return": {} } - -x-blockdev-del ------------- -Since 2.5 - -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. - -This command is still a work in progress and is considered -experimental. Stay away from it unless you want to help with its -development. - -Arguments: - -- "node-name": Name of the graph node to delete (json-string) - -Example: - --> { "execute": "blockdev-add", - "arguments": { - "driver": "qcow2", - "node-name": "node0", - "file": { - "driver": "file", - "filename": "test.qcow2" - } - } - } - -<- { "return": {} } - --> { "execute": "x-blockdev-del", - "arguments": { "node-name": "node0" } - } -<- { "return": {} } - -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: -- if the guest has locked the tray, @force is false and the guest does not - respond to the eject request -- if the BlockBackend denoted by @device does not have a guest device attached - to it -- if the guest device does not have an actual tray and is empty, for instance - for floppy disk drives - -Arguments: - -- "device": block device name (deprecated, use @id instead) - (json-string, optional) -- "id": the name or QOM path of the guest device (json-string, optional) -- "force": 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 - (json-bool, optional) - -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": {} } - -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. - -Arguments: - -- "device": block device name (deprecated, use @id instead) - (json-string, optional) -- "id": the name or QOM path of the guest device (json-string, optional) - -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": {} } - -x-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. - -This command is still a work in progress and is considered experimental. -Stay away from it unless you want to help with its development. - -Arguments: - -- "device": block device name (deprecated, use @id instead) - (json-string, optional) -- "id": the name or QOM path of the guest device (json-string, optional) - -Example: - --> { "execute": "x-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": "x-blockdev-remove-medium", - "arguments": { "device": "ide0-1-0" } } - -<- { "return": {} } - -x-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. - -This command is still a work in progress and is considered experimental. -Stay away from it unless you want to help with its development. - -Arguments: - -- "device": block device name (deprecated, use @id instead) - (json-string, optional) -- "id": the name or QOM path of the guest device (json-string, optional) -- "node-name": root node of the BDS tree to insert into the block device - -Example: - --> { "execute": "blockdev-add", - "arguments": { { "node-name": "node0", - "driver": "raw", - "file": { "driver": "file", - "filename": "fedora.iso" } } } - -<- { "return": {} } - --> { "execute": "x-blockdev-insert-medium", - "arguments": { "id": "ide0-1-0", - "node-name": "node0" } } - -<- { "return": {} } - -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 @node is specified, it will be inserted under @parent. @child -may not be specified in this case. If both @parent and @child are -specified but @node is not, @child will be detached from @parent. - -Arguments: -- "parent": the id or name of the parent node (json-string) -- "child": the name of a child under the given parent node (json-string, optional) -- "node": the name of the node that will be added (json-string, optional) - -Note: this command is experimental, and not a stable API. It doesn't -support all kinds of operations, all kinds of children, nor all block -drivers. - -Warning: The data in a new quorum child MUST be consistent with that of -the rest of the array. - -Example: - -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": {} } - -Delete a quorum's node --> { "execute": "x-blockdev-change", - "arguments": { "parent": "disk1", - "child": "children.1" } } -<- { "return": {} } - -query-named-block-nodes ------------------------ - -Return a list of BlockDeviceInfo for all the named block driver nodes - -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 - } - } } ] } - -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. - -Arguments: - -- "device": block device name (deprecated, use @id instead) - (json-string, optional) -- "id": the name or QOM path of the guest device (json-string, optional) -- "filename": filename of the new image (json-string) -- "format": format of the new image (json-string, optional) -- "read-only-mode": new read-only mode (json-string, optional) - - Possible values: "retain" (default), "read-only", "read-write" - -Examples: - -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": {} } - -query-memdev ------------- - -Show memory devices information. - - -Example (1): - --> { "execute": "query-memdev" } -<- { "return": [ - { - "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" - } - ] - } - -query-memory-devices --------------------- - -Return a list of memory devices. - -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" - } ] } - -query-acpi-ospm-status ----------------------- - -Return list of ACPIOSTInfo for devices that support status reporting -via ACPI _OST method. - -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} - ]} - -rtc-reset-reinjection ---------------------- - -Reset the RTC interrupt reinjection backlog. - -Arguments: None. - -Example: - --> { "execute": "rtc-reset-reinjection" } -<- { "return": {} } - -trace-event-get-state ---------------------- - -Query the state of events. - -Arguments: - -- "name": Event name pattern (json-string). -- "vcpu": The vCPU to query, any vCPU by default (json-int, optional). - -An event is returned if: -- its name matches the "name" pattern, and -- if "vcpu" is given, the event has the "vcpu" property. - -Therefore, if "vcpu" is given, the operation will only match per-vCPU events, -returning their state on the specified vCPU. Special case: if "name" is an exact -match, "vcpu" is given and the event does not have the "vcpu" property, an error -is returned. - -Example: - --> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } } -<- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] } - -trace-event-set-state ---------------------- - -Set the state of events. - -Arguments: - -- "name": Event name pattern (json-string). -- "enable": Whether to enable or disable the event (json-bool). -- "ignore-unavailable": Whether to ignore errors for events that cannot be - changed (json-bool, optional). -- "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional). - -An event's state is modified if: -- its name matches the "name" pattern, and -- if "vcpu" is given, the event has the "vcpu" property. - -Therefore, if "vcpu" is given, the operation will only match per-vCPU events, -setting their state on the specified vCPU. Special case: if "name" is an exact -match, "vcpu" is given and the event does not have the "vcpu" property, an error -is returned. - -Example: - --> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } } -<- { "return": {} } - -input-send-event ----------------- - -Send input event to guest. - -Arguments: - -- "device": display device (json-string, optional) -- "head": display head (json-int, optional) -- "events": list of input events - -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. - -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": {} } - -Example (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": {} } - -Example (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": {} } - -block-set-write-threshold ------------- - -Change the write threshold for a block drive. The threshold is an offset, -thus must be non-negative. Default is no write threshold. -Setting the threshold to zero disables it. - -Arguments: - -- "node-name": the node name in the block driver state graph (json-string) -- "write-threshold": the write threshold in bytes (json-int) - -Example: - --> { "execute": "block-set-write-threshold", - "arguments": { "node-name": "mydev", - "write-threshold": 17179869184 } } -<- { "return": {} } - -Show rocker switch ------------------- - -Arguments: - -- "name": switch name - -Example: - --> { "execute": "query-rocker", "arguments": { "name": "sw1" } } -<- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} - -Show rocker switch ports ------------------------- - -Arguments: - -- "name": switch name - -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} - ]} - -Show rocker switch OF-DPA flow tables -------------------------------------- - -Arguments: - -- "name": switch name -- "tbl-id": (optional) flow table ID - -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...}, - ]} - -Show rocker OF-DPA group tables -------------------------------- - -Arguments: - -- "name": switch name -- "type": (optional) group type - -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} - ]} - -query-gic-capabilities ---------------- - -Return a list of GICCapability objects, describing supported GIC -(Generic Interrupt Controller) versions. - -Arguments: None - -Example: - --> { "execute": "query-gic-capabilities" } -<- { "return": [{ "version": 2, "emulated": true, "kernel": false }, - { "version": 3, "emulated": false, "kernel": true } ] } - -Show existing/possible CPUs ---------------------------- - -Arguments: None. - -Example for pseries machine type started with --smp 2,cores=2,maxcpus=4 -cpu POWER8: - --> { "execute": "query-hotpluggable-cpus" } -<- {"return": [ - { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core", - "vcpus-count": 1 }, - { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core", - "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} - ]}' - -Example 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} - } - ]} diff --git a/docs/qmp-events.txt b/docs/qmp-events.txt deleted file mode 100644 index e0a2365c63..0000000000 --- a/docs/qmp-events.txt +++ /dev/null @@ -1,731 +0,0 @@ - QEMU Machine Protocol Events - ============================ - -ACPI_DEVICE_OST ---------------- - -Emitted when guest executes ACPI _OST method. - - - data: ACPIOSTInfo type as described in qapi-schema.json - -{ "event": "ACPI_DEVICE_OST", - "data": { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0 } } - -BALLOON_CHANGE --------------- - -Emitted when the guest changes the actual BALLOON level. This -value is equivalent to the 'actual' field return by the -'query-balloon' command - -Data: - -- "actual": actual level of the guest memory balloon in bytes (json-number) - -Example: - -{ "event": "BALLOON_CHANGE", - "data": { "actual": 944766976 }, - "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } - -Note: this event is rate-limited. - -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. - -Data: - -- "device": Device name (json-string) -- "node-name": Node name (json-string, optional) -- "msg": Informative message (e.g., reason for the corruption) - (json-string) -- "offset": If the corruption resulted from an image access, this - is the host's access offset into the image - (json-int, optional) -- "size": If the corruption resulted from an image access, this - is the access size (json-int, optional) - -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 } } - -BLOCK_IO_ERROR --------------- - -Emitted when a disk I/O error occurs. - -Data: - -- "device": device name. This is always present for compatibility - reasons, but it can be empty ("") if the image does not - have a device name associated. (json-string) -- "node-name": 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. (json-string) -- "operation": I/O operation (json-string, "read" or "write") -- "action": action that has been taken, it's one of the following (json-string): - "ignore": error has been ignored - "report": error has been reported to the device - "stop": the VM is going to stop because of the error - -Example: - -{ "event": "BLOCK_IO_ERROR", - "data": { "device": "ide0-hd1", - "node-name": "#block212", - "operation": "write", - "action": "stop" }, - "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } - -Note: If action is "stop", a STOP event will eventually follow the -BLOCK_IO_ERROR event. - -BLOCK_JOB_CANCELLED -------------------- - -Emitted when a block job has been cancelled. - -Data: - -- "type": Job type (json-string; "stream" for image streaming - "commit" for block commit) -- "device": Job identifier. Originally the device name but other - values are allowed since QEMU 2.7 (json-string) -- "len": Maximum progress value (json-int) -- "offset": Current progress value (json-int) - On success this is equal to len. - On failure this is less than len. -- "speed": Rate limit, bytes per second (json-int) - -Example: - -{ "event": "BLOCK_JOB_CANCELLED", - "data": { "type": "stream", "device": "virtio-disk0", - "len": 10737418240, "offset": 134217728, - "speed": 0 }, - "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } - -BLOCK_JOB_COMPLETED -------------------- - -Emitted when a block job has completed. - -Data: - -- "type": Job type (json-string; "stream" for image streaming - "commit" for block commit) -- "device": Job identifier. Originally the device name but other - values are allowed since QEMU 2.7 (json-string) -- "len": Maximum progress value (json-int) -- "offset": Current progress value (json-int) - On success this is equal to len. - On failure this is less than len. -- "speed": Rate limit, bytes per second (json-int) -- "error": Error message (json-string, optional) - 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. - -Example: - -{ "event": "BLOCK_JOB_COMPLETED", - "data": { "type": "stream", "device": "virtio-disk0", - "len": 10737418240, "offset": 10737418240, - "speed": 0 }, - "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } - -BLOCK_JOB_ERROR ---------------- - -Emitted when a block job encounters an error. - -Data: - -- "device": Job identifier. Originally the device name but other - values are allowed since QEMU 2.7 (json-string) -- "operation": I/O operation (json-string, "read" or "write") -- "action": action that has been taken, it's one of the following (json-string): - "ignore": error has been ignored, the job may fail later - "report": error will be reported and the job canceled - "stop": error caused job to be paused - -Example: - -{ "event": "BLOCK_JOB_ERROR", - "data": { "device": "ide0-hd1", - "operation": "write", - "action": "stop" }, - "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } - -BLOCK_JOB_READY ---------------- - -Emitted when a block job is ready to complete. - -Data: - -- "type": Job type (json-string; "stream" for image streaming - "commit" for block commit) -- "device": Job identifier. Originally the device name but other - values are allowed since QEMU 2.7 (json-string) -- "len": Maximum progress value (json-int) -- "offset": Current progress value (json-int) - On success this is equal to len. - On failure this is less than len. -- "speed": Rate limit, bytes per second (json-int) - -Example: - -{ "event": "BLOCK_JOB_READY", - "data": { "device": "drive0", "type": "mirror", "speed": 0, - "len": 2097152, "offset": 2097152 } - "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } - -Note: The "ready to complete" status is always reset by a BLOCK_JOB_ERROR -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. - -Data: - -- "device": device name (json-string, optional) -- "path": device path (json-string) - -{ "event": "DEVICE_DELETED", - "data": { "device": "virtio-net-pci-0", - "path": "/machine/peripheral/virtio-net-pci-0" }, - "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } - -DEVICE_TRAY_MOVED ------------------ - -It's emitted whenever the tray of a removable device is moved by the guest -or by HMP/QMP commands. - -Data: - -- "device": 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. (json-string) -- "id": The name or QOM path of the guest device (json-string) -- "tray-open": true if the tray has been opened or false if it has been closed - (json-bool) - -{ "event": "DEVICE_TRAY_MOVED", - "data": { "device": "ide1-cd0", - "id": "/machine/unattached/device[22]", - "tray-open": true - }, - "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } - -DUMP_COMPLETED --------------- - -Emitted when the guest has finished one memory dump. - -Data: - -- "result": DumpQueryResult type described in qapi-schema.json -- "error": Error message when dump failed. This is only a - human-readable string provided when dump failed. It should not be - parsed in any way (json-string, optional) - -Example: - -{ "event": "DUMP_COMPLETED", - "data": {"result": {"total": 1090650112, "status": "completed", - "completed": 1090650112} } } - -GUEST_PANICKED --------------- - -Emitted when guest OS panic is detected. - -Data: - -- "action": Action that has been taken (json-string, currently always "pause"). - -Example: - -{ "event": "GUEST_PANICKED", - "data": { "action": "pause" } } - -MEM_UNPLUG_ERROR --------------------- -Emitted when memory hot unplug error occurs. - -Data: - -- "device": device name (json-string) -- "msg": Informative message (e.g., reason for the error) (json-string) - -Example: - -{ "event": "MEM_UNPLUG_ERROR" - "data": { "device": "dimm1", - "msg": "acpi: device unplug for unsupported device" - }, - "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } - -NIC_RX_FILTER_CHANGED ---------------------- - -The event is emitted once until the query command is executed, -the first event will always be emitted. - -Data: - -- "name": net client name (json-string) -- "path": device path (json-string) - -{ "event": "NIC_RX_FILTER_CHANGED", - "data": { "name": "vnet0", - "path": "/machine/peripheral/vnet0/virtio-backend" }, - "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } -} - -POWERDOWN ---------- - -Emitted when the Virtual Machine is powered down through the power -control system, such as via ACPI. - -Data: None. - -Example: - -{ "event": "POWERDOWN", - "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } - -QUORUM_FAILURE --------------- - -Emitted by the Quorum block driver if it fails to establish a quorum. - -Data: - -- "reference": device name if defined else node name. -- "sector-num": Number of the first sector of the failed read operation. -- "sectors-count": Failed read operation sector count. - -Example: - -{ "event": "QUORUM_FAILURE", - "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 }, - "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } - -Note: this event is rate-limited. - -QUORUM_REPORT_BAD ------------------ - -Emitted to report a corruption of a Quorum file. - -Data: - -- "type": Quorum operation type -- "error": Error message (json-string, optional) - 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. -- "node-name": The graph node name of the block driver state. -- "sector-num": Number of the first sector of the failed read operation. -- "sectors-count": Failed read operation sector count. - -Example: - -Read operation: -{ "event": "QUORUM_REPORT_BAD", - "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, - "type": "read" }, - "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } - -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 } } - -Note: this event is rate-limited. - -RESET ------ - -Emitted when the Virtual Machine is reset. - -Data: None. - -Example: - -{ "event": "RESET", - "timestamp": { "seconds": 1267041653, "microseconds": 9518 } } - -RESUME ------- - -Emitted when the Virtual Machine resumes execution. - -Data: None. - -Example: - -{ "event": "RESUME", - "timestamp": { "seconds": 1271770767, "microseconds": 582542 } } - -RTC_CHANGE ----------- - -Emitted when the guest changes the RTC time. - -Data: - -- "offset": Offset between base RTC clock (as specified by -rtc base), and -new RTC clock value (json-number) - -Example: - -{ "event": "RTC_CHANGE", - "data": { "offset": 78 }, - "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } - -Note: this event is rate-limited. - -SHUTDOWN --------- - -Emitted when the Virtual Machine has shut down, indicating that qemu -is about to exit. - -Data: None. - -Example: - -{ "event": "SHUTDOWN", - "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } - -Note: If the command-line option "-no-shutdown" has been specified, a STOP -event will eventually follow the SHUTDOWN event. - -SPICE_CONNECTED ---------------- - -Emitted when a SPICE client connects. - -Data: - -- "server": Server information (json-object) - - "host": IP address (json-string) - - "port": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") -- "client": Client information (json-object) - - "host": IP address (json-string) - - "port": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") - -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"} -}} - -SPICE_DISCONNECTED ------------------- - -Emitted when a SPICE client disconnects. - -Data: - -- "server": Server information (json-object) - - "host": IP address (json-string) - - "port": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") -- "client": Client information (json-object) - - "host": IP address (json-string) - - "port": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") - -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"} -}} - -SPICE_INITIALIZED ------------------ - -Emitted after initial handshake and authentication takes place (if any) -and the SPICE channel is up and running - -Data: - -- "server": Server information (json-object) - - "host": IP address (json-string) - - "port": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") - - "auth": authentication method (json-string, optional) -- "client": Client information (json-object) - - "host": IP address (json-string) - - "port": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") - - "connection-id": spice connection id. All channels with the same id - belong to the same spice session (json-int) - - "channel-type": channel type. "1" is the main control channel, filter for - this one if you want track spice sessions only (json-int) - - "channel-id": channel id. Usually "0", might be different needed when - multiple channels of the same type exist, such as multiple - display channels in a multihead setup (json-int) - - "tls": whevener the channel is encrypted (json-bool) - -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} -}} - -SPICE_MIGRATE_COMPLETED ------------------------ - -Emitted when SPICE migration has completed - -Data: None. - -Example: - -{ "timestamp": {"seconds": 1290688046, "microseconds": 417172}, - "event": "SPICE_MIGRATE_COMPLETED" } - -MIGRATION ---------- - -Emitted when a migration event happens - -Data: None. - - - "status": migration status - See MigrationStatus in ~/qapi-schema.json for possible values - -Example: - -{"timestamp": {"seconds": 1432121972, "microseconds": 744001}, - "event": "MIGRATION", "data": {"status": "completed"}} - -MIGRATION_PASS --------------- - -Emitted from the source side of a migration at the start of each pass -(when it syncs the dirty bitmap) - -Data: None. - - - "pass": An incrementing count (starting at 1 on the first pass) - -Example: -{"timestamp": {"seconds": 1449669631, "microseconds": 239225}, - "event": "MIGRATION_PASS", "data": {"pass": 2}} - -STOP ----- - -Emitted when the Virtual Machine is stopped. - -Data: None. - -Example: - -{ "event": "STOP", - "timestamp": { "seconds": 1267041730, "microseconds": 281295 } } - -SUSPEND -------- - -Emitted when guest enters S3 state. - -Data: None. - -Example: - -{ "event": "SUSPEND", - "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } - -SUSPEND_DISK ------------- - -Emitted when the guest makes a request to enter S4 state. - -Data: None. - -Example: - -{ "event": "SUSPEND_DISK", - "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } - -Note: QEMU shuts down when entering S4 state. - -VNC_CONNECTED -------------- - -Emitted when a VNC client establishes a connection. - -Data: - -- "server": Server information (json-object) - - "host": IP address (json-string) - - "service": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") - - "auth": authentication method (json-string, optional) -- "client": Client information (json-object) - - "host": IP address (json-string) - - "service": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") - -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 } } - - -Note: This event is emitted before any authentication takes place, thus -the authentication ID is not provided. - -VNC_DISCONNECTED ----------------- - -Emitted when the connection is closed. - -Data: - -- "server": Server information (json-object) - - "host": IP address (json-string) - - "service": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") - - "auth": authentication method (json-string, optional) -- "client": Client information (json-object) - - "host": IP address (json-string) - - "service": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") - - "x509_dname": TLS dname (json-string, optional) - - "sasl_username": SASL username (json-string, optional) - -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 } } - -VNC_INITIALIZED ---------------- - -Emitted after authentication takes place (if any) and the VNC session is -made active. - -Data: - -- "server": Server information (json-object) - - "host": IP address (json-string) - - "service": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") - - "auth": authentication method (json-string, optional) -- "client": Client information (json-object) - - "host": IP address (json-string) - - "service": port number (json-string) - - "family": address family (json-string, "ipv4" or "ipv6") - - "x509_dname": TLS dname (json-string, optional) - - "sasl_username": SASL username (json-string, optional) - -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 } } - -VSERPORT_CHANGE ---------------- - -Emitted when the guest opens or closes a virtio-serial port. - -Data: - -- "id": device identifier of the virtio-serial port (json-string) -- "open": true if the guest has opened the virtio-serial port (json-bool) - -Example: - -{ "event": "VSERPORT_CHANGE", - "data": { "id": "channel0", "open": true }, - "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } - -Note: this event is rate-limited separately for each "id". - -WAKEUP ------- - -Emitted when the guest has woken up from S3 and is running. - -Data: None. - -Example: - -{ "event": "WAKEUP", - "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } - -WATCHDOG --------- - -Emitted when the watchdog device's timer is expired. - -Data: - -- "action": Action that has been taken, it's one of the following (json-string): - "reset", "shutdown", "poweroff", "pause", "debug", or "none" - -Example: - -{ "event": "WATCHDOG", - "data": { "action": "reset" }, - "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } - -Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is -followed respectively by the RESET, SHUTDOWN, or STOP events. - -Note: this event is rate-limited. diff --git a/docs/qmp-intro.txt b/docs/qmp-intro.txt index f6a3a031e9..60deafbae6 100644 --- a/docs/qmp-intro.txt +++ b/docs/qmp-intro.txt @@ -16,8 +16,7 @@ QMP is JSON[1] based and features the following: For detailed information on QMP's usage, please, refer to the following files: o qmp-spec.txt QEMU Machine Protocol current specification -o qmp-commands.txt QMP supported commands (auto-generated at build-time) -o qmp-events.txt List of available asynchronous events +o qemu-qmp-ref.html QEMU QMP commands and events (auto-generated at build-time) [1] http://www.json.org diff --git a/docs/replay.txt b/docs/replay.txt index 779c6c059e..347b2ff055 100644 --- a/docs/replay.txt +++ b/docs/replay.txt @@ -195,3 +195,17 @@ Queue is flushed at checkpoints and information about processed requests is recorded to the log. In replay phase the queue is matched with events read from the log. Therefore block devices requests are processed deterministically. + +Network devices +--------------- + +Record and replay for network interactions is performed with the network filter. +Each backend must have its own instance of the replay filter as follows: + -netdev user,id=net1 -device rtl8139,netdev=net1 + -object filter-replay,id=replay,netdev=net1 + +Replay network filter is used to record and replay network packets. While +recording the virtual machine this filter puts all packets coming from +the outer world into the log. In replay mode packets from the log are +injected into the network device. All interactions with network backend +in replay mode are disabled. diff --git a/docs/specs/fw_cfg.txt b/docs/specs/fw_cfg.txt index 7a5f8c7824..08c00bdf44 100644 --- a/docs/specs/fw_cfg.txt +++ b/docs/specs/fw_cfg.txt @@ -33,6 +33,10 @@ the selector value is between 0x4000-0x7fff or 0xc000-0xffff. NOTE: As of QEMU v2.4, writes to the fw_cfg data register are no longer supported, and will be ignored (treated as no-ops)! +NOTE: As of QEMU v2.9, writes are reinstated, but only through the DMA + interface (see below). Furthermore, writeability of any specific item is + governed independently of Bit14 in the selector key value. + Bit15 of the selector register indicates whether the configuration setting is architecture specific. A value of 0 means the item is a generic configuration item. A value of 1 means the item is specific @@ -43,7 +47,7 @@ value between 0x8000-0xffff. == Data Register == -* Read/Write (writes ignored as of QEMU v2.4) +* Read/Write (writes ignored as of QEMU v2.4, but see the DMA interface) * Location: platform dependent (IOport [*] or MMIO) * Width: 8-bit (if IOport), 8/16/32/64-bit (if MMIO) * Endianness: string-preserving @@ -134,8 +138,8 @@ struct FWCfgFile { /* an individual file entry, 64 bytes total */ === All Other Data Items === -Please consult the QEMU source for the most up-to-date and authoritative -list of selector keys and their respective items' purpose and format. +Please consult the QEMU source for the most up-to-date and authoritative list +of selector keys and their respective items' purpose, format and writeability. === Ranges === @@ -144,13 +148,15 @@ items, and up to 0x4000 architecturally specific ones. Selector Reg. Range Usage --------------- ----------- -0x0000 - 0x3fff Generic (0x0000 - 0x3fff, RO) +0x0000 - 0x3fff Generic (0x0000 - 0x3fff, generally RO, possibly RW through + the DMA interface in QEMU v2.9+) 0x4000 - 0x7fff Generic (0x0000 - 0x3fff, RW, ignored in QEMU v2.4+) -0x8000 - 0xbfff Arch. Specific (0x0000 - 0x3fff, RO) +0x8000 - 0xbfff Arch. Specific (0x0000 - 0x3fff, generally RO, possibly RW + through the DMA interface in QEMU v2.9+) 0xc000 - 0xffff Arch. Specific (0x0000 - 0x3fff, RW, ignored in v2.4+) -In practice, the number of allowed firmware configuration items is given -by the value of FW_CFG_MAX_ENTRY (see fw_cfg.h). +In practice, the number of allowed firmware configuration items depends on the +machine type/version. = Guest-side DMA Interface = @@ -182,6 +188,7 @@ The "control" field has the following bits: - Bit 1: Read - Bit 2: Skip - Bit 3: Select. The upper 16 bits are the selected index. + - Bit 4: Write When an operation is triggered, if the "control" field has bit 3 set, the upper 16 bits are interpreted as an index of a firmware configuration item. @@ -191,8 +198,17 @@ If the "control" field has bit 1 set, a read operation will be performed. "length" bytes for the current selector and offset will be copied into the physical RAM address specified by the "address" field. -If the "control" field has bit 2 set (and not bit 1), a skip operation will be -performed. The offset for the current selector will be advanced "length" bytes. +If the "control" field has bit 4 set (and not bit 1), a write operation will be +performed. "length" bytes will be copied from the physical RAM address +specified by the "address" field to the current selector and offset. QEMU +prevents starting or finishing the write beyond the end of the item associated +with the current selector (i.e., the item cannot be resized). Truncated writes +are dropped entirely. Writes to read-only items are also rejected. All of these +write errors set bit 0 (the error bit) in the "control" field. + +If the "control" field has bit 2 set (and neither bit 1 nor bit 4), a skip +operation will be performed. The offset for the current selector will be +advanced "length" bytes. To check the result, read the "control" field: error bit set -> something went wrong. @@ -234,3 +250,5 @@ Prefix "opt/org.qemu/" is reserved for QEMU itself. Use of names not beginning with "opt/" is potentially dangerous and entirely unsupported. QEMU will warn if you try. + +All externally provided fw_cfg items are read-only to the guest. diff --git a/docs/specs/pci-ids.txt b/docs/specs/pci-ids.txt index fd27c677d4..16fdb0c93f 100644 --- a/docs/specs/pci-ids.txt +++ b/docs/specs/pci-ids.txt @@ -57,7 +57,10 @@ PCI devices (other than virtio): 1b36:0005 PCI test device (docs/specs/pci-testdev.txt) 1b36:0006 PCI Rocker Ethernet switch device 1b36:0007 PCI SD Card Host Controller Interface (SDHCI) +1b36:0008 PCIe host bridge +1b36:0009 PCI Expander Bridge (-device pxb) 1b36:000a PCI-PCI bridge (multiseat) +1b36:000b PCIe Expander Bridge (-device pxb-pcie) All these devices are documented in docs/specs. diff --git a/docs/specs/vhost-user.txt b/docs/specs/vhost-user.txt index d70bd83b13..036890feb0 100644 --- a/docs/specs/vhost-user.txt +++ b/docs/specs/vhost-user.txt @@ -259,6 +259,7 @@ Protocol features #define VHOST_USER_PROTOCOL_F_LOG_SHMFD 1 #define VHOST_USER_PROTOCOL_F_RARP 2 #define VHOST_USER_PROTOCOL_F_REPLY_ACK 3 +#define VHOST_USER_PROTOCOL_F_MTU 4 Message types ------------- @@ -470,6 +471,21 @@ Message types The first 6 bytes of the payload contain the mac address of the guest to allow the vhost user backend to construct and broadcast the fake RARP. + * VHOST_USER_NET_SET_MTU + + Id: 20 + Equivalent ioctl: N/A + Master payload: u64 + + Set host MTU value exposed to the guest. + This request should be sent only when VIRTIO_NET_F_MTU feature has been + successfully negotiated, VHOST_USER_F_PROTOCOL_FEATURES is present in + VHOST_USER_GET_FEATURES and protocol feature bit + VHOST_USER_PROTOCOL_F_NET_MTU is present in + VHOST_USER_GET_PROTOCOL_FEATURES. + If VHOST_USER_PROTOCOL_F_REPLY_ACK is negotiated, slave must respond + with zero in case the specified MTU is valid, or non-zero otherwise. + VHOST_USER_PROTOCOL_F_REPLY_ACK: ------------------------------- The original vhost-user specification only demands replies for certain diff --git a/docs/usb-storage.txt b/docs/usb-storage.txt index fbc1f2edd8..551af6f88b 100644 --- a/docs/usb-storage.txt +++ b/docs/usb-storage.txt @@ -34,7 +34,7 @@ with tree logical units: Number three emulates the classic bulk-only transport protocol too. It's called "usb-bot". It shares most code with "usb-storage", and the guest will not be able to see the difference. The qemu command -line interface is simliar to usb-uas though, i.e. no automatic scsi +line interface is similar to usb-uas though, i.e. no automatic scsi disk creation. It also features support for up to 16 LUNs. The LUN numbers must be continuous, i.e. for three devices you must use 0+1+2. The 0+1+5 numbering from the "usb-uas" example isn't going to work diff --git a/docs/usb2.txt b/docs/usb2.txt index c7a445afcd..b9e7548073 100644 --- a/docs/usb2.txt +++ b/docs/usb2.txt @@ -19,7 +19,7 @@ the controller so the USB 2.0 bus gets a individual name, for example '-device usb-ehci,id=ehci". This will give you a USB 2.0 bus named "ehci.0". -I strongly recomment to also use -device to attach usb devices because +I strongly recommend to also use -device to attach usb devices because you can specify the bus they should be attached to this way. Here is a complete example: |