From 0b8ff5672665c3792c27c02d9d05e0951c03d440 Mon Sep 17 00:00:00 2001
From: Luo Yifan <luoyifan_yewu@cmss.chinamobile.com>
Date: Wed, 30 Nov 2022 18:13:36 +0800
Subject: [PATCH 14/24] docs: introduces new vhostuser disk type
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

     <disk type='vhostuser' device='disk'>
       <driver name='qemu' type='raw'/>
       <source type='unix' path='/tmp/vhost-blk.sock'>
         <reconnect enabled='yes' timeout='10'/>
       </source>
       <target dev='vda' bus='virtio'/>
     </disk>

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
(cherry picked from commit e88bdaf789b6f1cc5347b217240f15afd86a94c1)
Signed-off-by: Luo Yifan <luoyifan_yewu@cmss.chinamobile.com>
---
 docs/formatdomain.html.in     | 51 ++++++++++++++++++++++++++++++++++-
 docs/schemas/domaincommon.rng | 19 +++++++++++++
 2 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index aaeb05961f..5860ec9f20 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -2977,6 +2977,13 @@
     &lt;/source&gt;
     &lt;target dev='vde' bus='virtio'/&gt;
   &lt;/disk&gt;
+  &lt;disk type='vhostuser' device='disk'&gt;
+    &lt;driver name='qemu' type='raw'/&gt;
+    &lt;source type='unix' path='/tmp/vhost-blk.sock'&gt;
+      &lt;reconnect enabled='yes' timeout='10'/&gt;
+    &lt;/source&gt;
+    &lt;target dev='vdf' bus='virtio'/&gt;
+  &lt;/disk&gt;
 &lt;/devices&gt;
 ...</pre>
 
@@ -2991,7 +2998,8 @@
             "dir" (<span class="since">since 0.7.5</span>),
             "network" (<span class="since">since 0.8.7</span>), or
             "volume" (<span class="since">since 1.0.5</span>), or
-            "nvme" (<span class="since">since 6.0.0</span>)
+            "nvme" (<span class="since">since 6.0.0</span>), or
+            "vhostuser" (<span class="since">since 6.2.0</span>)
             and refer to the underlying source for the disk.
             <span class="since">Since 0.0.3</span>
             </dd>
@@ -3217,6 +3225,31 @@
               <code>&lt;disk type='block'&gt;</code> and therefore lower
               latencies can be achieved.
               </dd>
+              <dt><code>vhostuser</code></dt>
+              <dd>
+              Enables the hypervisor to connect to another process using vhost-user
+              protocol. Requires shared memory configured for the VM, for more details
+              see <code>access</code> mode for
+              <code>memoryBacking &lt;#elementsMemoryBacking&gt;</code> element.
+
+              The <code>source</code> element has following mandatory attributes:
+              <dl>
+                <dt><code>type</code></dt>
+                <dd>The type of char device. Currently only <code>unix</code> type
+                is supported.
+                </dd>
+
+                <dt><code>path</code></dt>
+                <dd>Path to the unix socket to be used as disk source.
+                </dd>
+              </dl>
+
+              Note that the vhost server replaces both the disk frontend and backend
+              thus almost all of the disk properties can't be configured via the
+              <code>&lt;disk&gt;</code> XML for this disk type. Additionally features
+              such as blockjobs, incremental backups and snapshots are not supported 
+              for this disk type.
+              </dd>
           </dl>
         With "file", "block", and "volume", one or more optional
         sub-elements <code>seclabel</code>, <a href="#seclabel">described
@@ -3424,6 +3457,22 @@
             Note that '0' is considered as if the value is not provided.
             <span class="since">Since 6.2.0</span>
           </dd>
+          <dt><code>reconnect</code></dt>
+          <dd>
+            For disk type <code>vhostuser</code> configures reconnect timeout 
+            if the connection is lost. It has two mandatory attributes:
+            <dl>
+              <dt><code>enabled</code></dt>
+              <dd>If the reconnect feature is enabled, accepts<code>yes</code>
+              and <code>no</code>
+              </dd>
+
+              <dt><code>timeout</code></dt>
+              <dd>The amount of seconds after which hypervisor tries to reconnect.
+              </dd>
+            </dl>
+            <span class="since">Since 6.2.0</span>
+          </dd>
         </dl>
 
         <p>
diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index 1807df521c..764f826df4 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -1631,6 +1631,7 @@
       <ref name="diskSourceNetwork"/>
       <ref name="diskSourceVolume"/>
       <ref name="diskSourceNvme"/>
+      <ref name="diskSourceVhostUser"/>
     </choice>
   </define>
 
@@ -2103,6 +2104,24 @@
     </optional>
   </define>
 
+  <define name="diskSourceVhostUser">
+    <attribute name="type">
+      <value>vhostuser</value>
+    </attribute>
+    <element name="source">
+      <attribute name="type">
+        <value>unix</value>
+      </attribute>
+      <attribute name="path">
+        <ref name="absFilePath"/>
+      </attribute>
+      <optional>
+         <ref name="reconnect"/>
+      </optional>
+      <empty/>
+    </element>
+  </define>
+
   <define name="diskTarget">
     <data type="string">
       <param name="pattern">(ioemu:)?(fd|hd|sd|vd|xvd|ubd)[a-zA-Z0-9_]+</param>
-- 
2.27.0