docs/system/ivshmem.rst

   1 .. _pcsys_005fivshmem:
   2
   3 Inter-VM Shared Memory device
   4 -----------------------------
   5
   6 On Linux hosts, a shared memory device is available. The basic syntax
   7 is:
   8
   9 .. parsed-literal::
  10
  11    |qemu_system_x86| -device ivshmem-plain,memdev=hostmem
  12
  13 where hostmem names a host memory backend. For a POSIX shared memory
  14 backend, use something like
  15
  16 ::
  17
  18    -object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=hostmem
  19
  20 If desired, interrupts can be sent between guest VMs accessing the same
  21 shared memory region. Interrupt support requires using a shared memory
  22 server and using a chardev socket to connect to it. The code for the
  23 shared memory server is qemu.git/contrib/ivshmem-server. An example
  24 syntax when using the shared memory server is:
  25
  26 .. parsed-literal::
  27
  28    # First start the ivshmem server once and for all
  29    ivshmem-server -p pidfile -S path -m shm-name -l shm-size -n vectors
  30
  31    # Then start your qemu instances with matching arguments
  32    |qemu_system_x86| -device ivshmem-doorbell,vectors=vectors,chardev=id
  33                     -chardev socket,path=path,id=id
  34
  35 When using the server, the guest will be assigned a VM ID (>=0) that
  36 allows guests using the same server to communicate via interrupts.
  37 Guests can read their VM ID from a device register (see
  38 ivshmem-spec.txt).
  39
  40 Migration with ivshmem
  41 ~~~~~~~~~~~~~~~~~~~~~~
  42
  43 With device property ``master=on``, the guest will copy the shared
  44 memory on migration to the destination host. With ``master=off``, the
  45 guest will not be able to migrate with the device attached. In the
  46 latter case, the device should be detached and then reattached after
  47 migration using the PCI hotplug support.
  48
  49 At most one of the devices sharing the same memory can be master. The
  50 master must complete migration before you plug back the other devices.
  51
  52 ivshmem and hugepages
  53 ~~~~~~~~~~~~~~~~~~~~~
  54
  55 Instead of specifying the <shm size> using POSIX shm, you may specify a
  56 memory backend that has hugepage support:
  57
  58 .. parsed-literal::
  59
  60    |qemu_system_x86| -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
  61                     -device ivshmem-plain,memdev=mb1
  62
  63 ivshmem-server also supports hugepages mount points with the ``-m``
  64 memory path argument.