qemu/docs/system/ivshmem.rst
Paolo Bonzini 324b2298fe docs/system: convert Texinfo documentation to rST
Apart from targets.rst, which was written by hand, this is an automated
conversion obtained with the following command:

  makeinfo --force -o - --docbook \
    -D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' \
    -D 'qemu_system     QEMU_SYSTEM_MACRO' \
    $texi | pandoc -f docbook -t rst+smart | perl -e '
      $/=undef;
      $_ = <>;
      s/^-  − /-  /gm;
      s/QEMU_SYSTEM_MACRO/|qemu_system|/g;
      s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g;
      s/(?=::\n\n +\|qemu)/.. parsed-literal/g;
      s/:\n\n::$/::/gm;
      print' > $rst

In addition, the following changes were made manually:

- target-i386.rst and target-mips.rst: replace CPU model documentation with
  an include directive

- monitor.rst: replace the command section with a comment

- images.rst: add toctree

- target-arm.rst: Replace use of :math: (which Sphinx complains
  about) with :sup:, and hide it behind |I2C| and |I2C| substitutions.

Content that is not @included remains exclusive to qemu-doc.texi.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20200228153619.9906-20-peter.maydell@linaro.org
Message-id: 20200226113034.6741-19-pbonzini@redhat.com
[PMM: Fixed target-arm.rst use of :math:; remove out of date
 note about images.rst from commit message; fixed expansion
 of |qemu_system_x86|; use parsed-literal in invocation.rst
 when we want to use |qemu_system_x86|; fix incorrect subsection
 level for "OS requirements" in target-i386.rst; fix incorrect
 syntax for making links to other sections of the manual]
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-03-06 10:05:12 +00:00

65 lines
2.2 KiB
ReStructuredText

.. _pcsys_005fivshmem:
Inter-VM Shared Memory device
-----------------------------
On Linux hosts, a shared memory device is available. The basic syntax
is:
.. parsed-literal::
|qemu_system_x86| -device ivshmem-plain,memdev=hostmem
where hostmem names a host memory backend. For a POSIX shared memory
backend, use something like
::
-object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=hostmem
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:
.. parsed-literal::
# First start the ivshmem server once and for all
ivshmem-server -p pidfile -S path -m shm-name -l shm-size -n vectors
# Then start your qemu instances with matching arguments
|qemu_system_x86| -device ivshmem-doorbell,vectors=vectors,chardev=id
-chardev socket,path=path,id=id
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).
Migration with ivshmem
~~~~~~~~~~~~~~~~~~~~~~
With device property ``master=on``, the guest will copy the shared
memory on migration to the destination host. With ``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.
ivshmem and hugepages
~~~~~~~~~~~~~~~~~~~~~
Instead of specifying the <shm size> using POSIX shm, you may specify a
memory backend that has hugepage support:
.. parsed-literal::
|qemu_system_x86| -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
-device ivshmem-plain,memdev=mb1
ivshmem-server also supports hugepages mount points with the ``-m``
memory path argument.