aboutsummaryrefslogtreecommitdiff
path: root/qemu-doc.texi
diff options
context:
space:
mode:
authorCam Macdonell <cam@cs.ualberta.ca>2010-07-27 10:54:13 -0600
committerAnthony Liguori <aliguori@us.ibm.com>2010-08-10 16:25:16 -0500
commit6cbf4c8c6416237e9c323661b87d60792a9d51af (patch)
tree6c44bc8d4b79b334ba3a89211baa3cb4dfded594 /qemu-doc.texi
parent2431296806bc7a40c29b7775e16f36dc1cda4d06 (diff)
RESEND: Inter-VM shared memory PCI device
resend for bug fix related to removal of irqfd Support an inter-vm shared memory device that maps a shared-memory object as a PCI device in the guest. This patch also supports interrupts between guest by communicating over a unix domain socket. This patch applies to the qemu-kvm repository. -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>] Interrupts are supported between multiple VMs by using a shared memory server by using a chardev socket. -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>] [,chardev=<id>][,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master] -chardev socket,path=<path>,id=<id> The shared memory server, sample programs and init scripts are in a git repo here: www.gitorious.org/nahanni Signed-off-by: Cam Macdonell <cam@cs.ualberta.ca> Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
Diffstat (limited to 'qemu-doc.texi')
-rw-r--r--qemu-doc.texi43
1 files changed, 43 insertions, 0 deletions
diff --git a/qemu-doc.texi b/qemu-doc.texi
index e67bf44ff3..55a966fe71 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -706,6 +706,49 @@ Using the @option{-net socket} option, it is possible to make VLANs
that span several QEMU instances. See @ref{sec_invocation} to have a
basic example.
+@section Other Devices
+
+@subsection Inter-VM Shared Memory device
+
+With KVM enabled on a Linux host, a shared memory device is available. Guests
+map a POSIX shared memory region into the guest as a PCI device that enables
+zero-copy communication to the application level of the guests. The basic
+syntax is:
+
+@example
+qemu -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>]
+@end example
+
+If desired, interrupts can be sent between guest VMs accessing the same shared
+memory region. Interrupt support requires using a shared memory server and
+using a chardev socket to connect to it. The code for the shared memory server
+is qemu.git/contrib/ivshmem-server. An example syntax when using the shared
+memory server is:
+
+@example
+qemu -device ivshmem,size=<size in format accepted by -m>[,chardev=<id>]
+ [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master]
+qemu -chardev socket,path=<path>,id=<id>
+@end example
+
+When using the server, the guest will be assigned a VM ID (>=0) that allows guests
+using the same server to communicate via interrupts. Guests can read their
+VM ID from a device register (see example code). Since receiving the shared
+memory region from the server is asynchronous, there is a (small) chance the
+guest may boot before the shared memory is attached. To allow an application
+to ensure shared memory is attached, the VM ID register will return -1 (an
+invalid VM ID) until the memory is attached. Once the shared memory is
+attached, the VM ID will return the guest's valid VM ID. With these semantics,
+the guest application can check to ensure the shared memory is attached to the
+guest before proceeding.
+
+The @option{role} argument can be set to either master or peer and will affect
+how the shared memory is migrated. With @option{role=master}, the guest will
+copy the shared memory on migration to the destination host. With
+@option{role=peer}, the guest will not be able to migrate with the device attached.
+With the @option{peer} case, the device should be detached and then reattached
+after migration using the PCI hotplug support.
+
@node direct_linux_boot
@section Direct Linux Boot