[libvirt] [RFC PATCH 1/5] doc: schema: Add basic documentation for the ivshmem support
Wang Rui
moon.wangrui at huawei.com
Wed Aug 6 09:41:59 UTC 2014
On 2014/8/6 0:48, Maxime Leroy wrote:
> This patch documents XML elements used for support of ivshmem
> devices.
>
> About ivshmem, please see the following documentation:
> http://git.qemu.org/?p=qemu.git;a=blob;f=docs/specs/ivshmem_device_spec.txt
> (Ivshmem documentation for qemu will be updated soon:
> https://lists.nongnu.org/archive/html/qemu-devel/2014-07/msg02974.html)
>
> In the devices section in the domain XML users may specify:
>
> - For ivshmem device using an ivshmem server:
>
> <ivshmem use_server='yes' role='master'/>
> <source file='/tmp/socket-ivshmem0'/>
I prefer to use <source mode='connect' path='/tmp/socket-ivshmem0'/> .
So when ParesXML and Format functions are needed, we can use
virDomainChrSourceDef*(), like vmchannel device.
What do you think about it ?
> <size unit='M'>32</size>
> <msi vectors='32' ioeventfd='on'/>
> </ivshmem>
>
> Note: the ivshmem server needs to be launched before
> creating the VM. It's not done by libvirt.
>
> - For ivshmem device not using an ivshmem server:
>
> <ivshmem use_server='no' role='peer'/>
> <source file='ivshmem1'/>
> <size unit='M'>32</size>
> </ivshmem>
>
> Note: the ivshmem shm needs to be created before
> creating the VM. It's not done by libvirt.
>
> Signed-off-by: Maxime Leroy <maxime.leroy at 6wind.com>
> ---
> docs/formatdomain.html.in | 72 +++++++++++++++++++++++++++++++++++++++++++
> docs/schemas/domaincommon.rng | 57 ++++++++++++++++++++++++++++++++++
> 2 files changed, 129 insertions(+)
>
> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index e5b1adb..9a9a6fa 100644
> --- a/docs/formatdomain.html.in
> +++ b/docs/formatdomain.html.in
> @@ -4035,6 +4035,78 @@ qemu-kvm -net nic,model=? /dev/null
> <code><model></code> element is mandatory.
> </p>
>
> + <h4><a name="elementsIvshmem">Ivshmem device</a></h4>
> +
> + <p>
> + An ivshmem (i.e. Inter-VM shared memory) device allows to share a memory
> + region (created on the host via the POSIX shared memory API) between
> + multiple QEMU processes running different guests.
> + For more information, please see the
> + <a href="http://git.qemu.org/?p=qemu.git;a=blob;f=docs/specs/ivshmem_device_spec.txt">
> + ivshmem documentation of qemu</a>.
> + </p>
> +
> +<pre>
> + ...
> + <devices>
> + <ivshmem use_server='yes' role='master'/>
> + <source file='/tmp/socket-ivshmem0'/>
> + <size unit='M'>32</size>
> + <msi vectors='32' ioeventfd='on'/>
> + </ivshmem>
> + <ivshmem use_server='no' role='peer'/>
> + <source file='ivshmem1'/>
> + <size unit='M'>32</size>
> + </ivshmem>
> + </devices>
> + ...</pre>
> +
> + <dl>
> + <dt><code>ivshmem</code></dt>
> + <dd>The <code>ivshmem</code> element has a mandatory <code>use_server</code>
> + attribute which takes the value "yes" or "no":
> + <dl>
> + <dt><code>"yes"</code></dt>
> + <dd>
> + Configure the ivshmen device to connect to the ivshmem server via a unix socket.
> + </dd>
> + <dt><code>"no"</code></dt>
> + <dd>
> + Configure the ivshmen device with a shared memory file.
> + </dd>
> + </dl>
> + </dd>
> + <dt><code>role</code></dt>
> + <dd>The <code>role</code> attribute is optional. It takes the value "master" or "peer":
> + <dl>
> + <dt><code>"master"</code></dt>
> + <dd>
> + On migration, the guest will copy the shared memory to the destination host.
> + </dd>
> + <dt><code>"peer"</code></dt>
> + <dd>
> + The device should be detached and then reattached after migration using
> + the PCI hotplug support.
> + </dd>
> + </dl>
> + Note: PCI hotplug is not supported for ivshmem device in libvirt.
> + </dd>
> + <dt><code>size</code></dt>
> + <dd>The optional <code>size</code> element specifies the size of the shared memory file.
> + </dd>
> + <dt><code>source</code></dt>
> + <dd>The <code>source</code> element is mandatory.
> + The <code>file</code> attribute specifies the ivshmem server socket file in server mode.
> + In non server mode, it specifies the shared memory file.
> + </dd>
> + <dt><code>msi</code></dt>
> + <dd>The optional <code>msi</code> element allows to enable MSI interrupts. This option
> + can only be used in server mode. The <code>vectors</code> attribute
> + allows to specify the number of interrupt vectors. The <code>ioeventd</code> attribute
> + allows to enable ioeventfd.
> + </dd>
> + </dl>
> +
> <h4><a name="elementsInput">Input devices</a></h4>
>
> <p>
> diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
> index 11f0fd0..8229921 100644
> --- a/docs/schemas/domaincommon.rng
> +++ b/docs/schemas/domaincommon.rng
> @@ -3220,6 +3220,62 @@
> </optional>
> </element>
> </define>
> +
> + <define name="ivshmem">
> + <element name="ivshmem">
> + <interleave>
> + <choice>
> + <group>
> + <attribute name="use_server">
> + <value>yes</value>
> + </attribute>
> + <optional>
> + <element name="msi">
> + <optional>
> + <ref name="ioeventfd"/>
> + </optional>
> + <optional>
> + <attribute name="vectors">
> + <ref name="unsignedInt"/>
> + </attribute>
> + </optional>
> + </element>
> + </optional>
> + </group>
> + <group>
> + <attribute name="use_server">
> + <value>no</value>
> + </attribute>
> + </group>
> + </choice>
> + <element name="source">
> + <attribute name="file">
> + <text/>
> + </attribute>
> + </element>
> + <optional>
> + <attribute name="role">
> + <choice>
> + <value>master</value>
> + <value>peer</value>
> + </choice>
> + </attribute>
> + </optional>
> + <optional>
> + <element name="size">
> + <ref name="scaledInteger"/>
> + </element>
> + </optional>
> + <optional>
> + <ref name="alias"/>
> + </optional>
> + <optional>
> + <ref name="address"/>
> + </optional>
> + </interleave>
> + </element>
> + </define>
> +
> <define name="memballoon">
> <element name="memballoon">
> <attribute name="model">
> @@ -3767,6 +3823,7 @@
> <ref name="redirfilter"/>
> <ref name="rng"/>
> <ref name="tpm"/>
> + <ref name="ivshmem"/>
> </choice>
> </zeroOrMore>
> <optional>
More information about the libvir-list
mailing list