From fdeccf932d05c527b3ea57207a03392d15001b73 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Fri, 28 Feb 2020 15:35:51 +0000 Subject: qemu-doc: split qemu-doc.texi in multiple files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In order to facilitate the reorganization of qemu-doc.texi content, as well as the conversion to rST/Sphinx, split it in multiple .texi files that are included from docs/system. The "other devices" section is renamed to ivshmem and placed last. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell Reviewed-by: Alex Bennée Tested-by: Alex Bennée Signed-off-by: Peter Maydell Message-id: 20200228153619.9906-6-peter.maydell@linaro.org Message-id: 20200226113034.6741-6-pbonzini@redhat.com Reviewed-by: Peter Maydell Signed-off-by: Peter Maydell --- docs/system/ivshmem.texi | 60 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 docs/system/ivshmem.texi (limited to 'docs/system/ivshmem.texi') diff --git a/docs/system/ivshmem.texi b/docs/system/ivshmem.texi new file mode 100644 index 0000000000..bd97719eaf --- /dev/null +++ b/docs/system/ivshmem.texi @@ -0,0 +1,60 @@ +@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 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. + -- cgit v1.2.3