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