From a7292e07df79b4633cf7297ef307c44550872b2b Mon Sep 17 00:00:00 2001
From: Roman Bogorodskiy <bogorodskiy@gmail.com>
Date: Fri, 7 Aug 2020 19:00:38 +0400
Subject: [PATCH] docs: formatdomain: document <audio> element
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the new <audio> element which allows to specify
host audio backend for a guest <sound> device, and update
the <sound> element description with the new <audio>
sub-element which specifies the other end of the mapping.

Signed-off-by: Roman Bogorodskiy <bogorodskiy@gmail.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
---
 docs/formatdomain.rst | 49 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index cd5b9b28e6..318e39177a 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -6572,6 +6572,55 @@ Valid values are:
 Each ``sound`` element has an optional sub-element ``<address>`` which can tie
 the device to a particular PCI slot, `documented above <#elementsAddress>`__.
 
+:since:`Since 6.7.0`, a sound device could be optionally mapped to the specific
+host audio backend using the ``<audio>`` sub-element:
+
+::
+
+   ...
+   <devices>
+     <sound model='ich7'>
+        <audio id='1'>
+     </sound>
+   </devices>
+   ...
+
+Where ``1`` is an id of the `audio device <#elementsAudio>`__.
+This is supported for bhyve only.
+
+:anchor:`<a id="elementsAudio"/>`
+
+Audio devices
+~~~~~~~~~~~~~
+
+A virtual audio device corresponds to a host audio backend that is mapped
+to the guest sound device. :since:`Since 6.7.0, bhyve only`
+
+``type``
+   The required ``type`` attribute specifies audio backend type.
+   Currently, the only supported value is 'oss'.
+
+``id``
+   Integer id of the audio device. Must be greater than 0.
+
+The 'oss' audio type supports additional configuration:
+
+::
+
+   ...
+   <devices>
+     <audio type='oss' id='1'>
+       <input dev='/dev/dsp0'/>
+       <output dev='/dev/dsp0'/>
+     </audio>
+   </devices>
+
+``input``
+   Input device. The required ``dev`` attribute specifies device path.
+
+``output``
+   Output device. The required ``dev`` attribute specifies device path.
+
 :anchor:`<a id="elementsWatchdog"/>`
 
 Watchdog device