From e88bdaf789b6f1cc5347b217240f15afd86a94c1 Mon Sep 17 00:00:00 2001
From: Pavel Hrdina <phrdina@redhat.com>
Date: Mon, 25 Jan 2021 15:59:02 +0100
Subject: [PATCH] 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>
---
 docs/formatdomain.rst         | 37 +++++++++++++++++++++++++++++++++--
 docs/schemas/domaincommon.rng | 19 ++++++++++++++++++
 2 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 3a2fe7fa16..0f78aa3a8c 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -2419,6 +2419,13 @@ paravirtualized driver is specified via the ``disk`` element.
        </source>
        <target dev='vde' bus='virtio'/>
      </disk>
+     <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='vdf' bus='virtio'/>
+     </disk>
    </devices>
    ...
 
@@ -2429,8 +2436,8 @@ paravirtualized driver is specified via the ``disk`` element.
    ``type``
       Valid values are "file", "block", "dir" ( :since:`since 0.7.5` ),
       "network" ( :since:`since 0.8.7` ), or "volume" ( :since:`since 1.0.5` ),
-      or "nvme" ( :since:`since 6.0.0` ) and refer to the underlying source for
-      the disk. :since:`Since 0.0.3`
+      or "nvme" ( :since:`since 6.0.0` ), or "vhostuser" ( :since:`since 7.1.0` )
+      and refer to the underlying source for the disk. :since:`Since 0.0.3`
    ``device``
       Indicates how the disk is to be exposed to the guest OS. Possible values
       for this attribute are "floppy", "disk", "cdrom", and "lun", defaulting to
@@ -2581,6 +2588,23 @@ paravirtualized driver is specified via the ``disk`` element.
       is not involved (compared to passing say ``/dev/nvme0n1`` via
       ``<disk type='block'>`` and therefore lower latencies can be achieved.
 
+   ``vhostuser``
+      Enables the hypervisor to connect to another process using vhost-user
+      protocol. Requires shared memory configured for the VM, for more details
+      see ``access`` mode for `memoryBacking <#elementsMemoryBacking>` element.
+
+      The ``source`` element has following mandatory attributes:
+
+      ``type``
+         The type of char device. Currently only ``unix`` type is supported.
+      ``path``
+         Path to the unix socket to be used as disk source.
+
+      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
+      ``<disk>`` XML for this disk type. Additionally features such as blockjobs,
+      incremental backups and snapshots are not supported for this disk type.
+
    With "file", "block", and "volume", one or more optional sub-elements
    ``seclabel``, `described below <#seclabel>`__ (and :since:`since 0.9.9` ),
    can be used to override the domain security labeling policy for just that
@@ -2703,6 +2727,15 @@ paravirtualized driver is specified via the ``disk`` element.
       of these attributes is omitted, then that field is assumed to be the
       default value for the current system. If both ``user`` and ``group``
       are intended to be default, then the entire element may be omitted.
+   ``reconnect``
+      For disk type ``vhostuser`` configures reconnect timeout if the connection
+      is lost. It has two mandatory attributes:
+
+      ``enabled``
+         If the reconnect feature is enabled, accepts ``yes`` and ``no``
+      ``timeout``
+         The amount of seconds after which hypervisor tries to reconnect.
+
 
    For a "file" or "volume" disk type which represents a cdrom or floppy (the
    ``device`` attribute), it is possible to define policy what to do with the
diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index 239ae3f347..7a2706a4fb 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -1646,6 +1646,7 @@
       <ref name="diskSourceNetwork"/>
       <ref name="diskSourceVolume"/>
       <ref name="diskSourceNvme"/>
+      <ref name="diskSourceVhostUser"/>
     </choice>
   </define>
 
@@ -2156,6 +2157,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>