From: Roman Bogorodskiy <bogorodskiy@gmail.com>
Date: Fri, 7 Aug 2020 15:00:38 +0000 (+0400)
Subject: docs: formatdomain: document <audio> element
X-Git-Tag: v6.7.0-rc1~36
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a7292e07df79b4633cf7297ef307c44550872b2b;p=thirdparty%2Flibvirt.git

docs: formatdomain: document <audio> element

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>
---

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