docs/system/ivshmem.texi

@node pcsys_ivshmem
@section Inter-VM Shared Memory device

On Linux hosts, a shared memory device is available.  The basic syntax
is:

@example
@value{qemu_system_x86} -device ivshmem-plain,memdev=@var{hostmem}
@end example

where @var{hostmem} names a host memory backend.  For a POSIX shared
memory backend, use something like

@example
-object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
@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
# First start the ivshmem server once and for all
ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}

# Then start your qemu instances with matching arguments
@value{qemu_system_x86} -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
                 -chardev socket,path=@var{path},id=@var{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 ivshmem-spec.txt).

@subsection Migration with ivshmem

With device property @option{master=on}, the guest will copy the shared
memory on migration to the destination host.  With @option{master=off},
the guest will not be able to migrate with the device attached.  In the
latter case, the device should be detached and then reattached after
migration using the PCI hotplug support.

At most one of the devices sharing the same memory can be master.  The
master must complete migration before you plug back the other devices.

@subsection ivshmem and hugepages

Instead of specifying the <shm size> using POSIX shm, you may specify
a memory backend that has hugepage support:

@example
@value{qemu_system_x86} -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
                 -device ivshmem-plain,memdev=mb1
@end example

ivshmem-server also supports hugepages mount points with the
@option{-m} memory path argument.