Re: [RFC PATCH 1/5] doc: schema: Add basic documentation for the ivshmem support

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxx>
> ---
>  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>&lt;model&gt;</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>
> +  ...
> +  &lt;devices&gt;
> +    &lt;ivshmem use_server='yes' role='master'/&gt;
> +      &lt;source file='/tmp/socket-ivshmem0'/&gt;
> +      &lt;size unit='M'&gt;32&lt;/size&gt;
> +      &lt;msi vectors='32' ioeventfd='on'/&gt;
> +    &lt;/ivshmem&gt;
> +    &lt;ivshmem use_server='no' role='peer'/&gt;
> +      &lt;source file='ivshmem1'/&gt;
> +      &lt;size unit='M'&gt;32&lt;/size&gt;
> +    &lt;/ivshmem&gt;
> +  &lt;/devices&gt;
> +  ...</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>


--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]