[Xen-devel] [PATCH v2 5/5] docs: add PV sound device config

[Oleksandr Grytsov <al1img@xxxxxxxxx>]

From: Oleksandr Grytsov <oleksandr_grytsov@xxxxxxxx>

Update documentation with virtual sound device

Signed-off-by: Oleksandr Grytsov <oleksandr_grytsov@xxxxxxxx>
Acked-by: Wei Liu <wei.liu2@xxxxxxxxxx>
---
 docs/man/xl.cfg.pod.5.in | 149 +++++++++++++++++++++++++++++++++++++++
 docs/man/xl.pod.1.in     |  30 ++++++++
 2 files changed, 179 insertions(+)

diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in
index 47d88243b1..f96bd1b9ad 100644
--- a/docs/man/xl.cfg.pod.5.in
+++ b/docs/man/xl.cfg.pod.5.in
@@ -1414,6 +1414,155 @@ we may break backward compatibility.
 
 =back
 
+=item B<vsnd=[ VCARD_SPEC, VCARD_SPEC, ... ]>
+
+Specifies the virtual sound cards to be provided to the guest.
+Each B<VCARD_SPEC> is a list, which has a form of
+"[VSND_ITEM_SPEC, VSND_ITEM_SPEC, ... ]" (without the quotes).
+The virtual sound card has hierarchical structure.
+Every card has a set of PCM devices and streams, each could be individually
+configured.
+
+B<VSND_ITEM_SPEC> describes individual item parameters.
+B<VSND_ITEM_SPEC> is a string of comma separated item parameters
+headed by item identifier. Each item parameter is C<KEY=VALUE> pair:
+
+=over 4
+
+"identifier, param = value, ...".
+
+=back
+
+Identifier shall be one of following values: "CARD", "PCM", "STREAM".
+The child item treated as belonging to the previously defined parent item.
+
+All parameters are optional.
+
+There are group of parameters which are common for all items.
+This group can be defined at higher level of the hierarchy and be fully or
+partially re-used by the underlying layers. These parameters are:
+
+=over 4
+
+* number of channels (min/max)
+
+* supported sample rates
+
+* supported sample formats
+
+=back
+
+E.g. one can define these values for the whole card, device or stream.
+Every underlying layer in turn can re-define some or all of them to better
+fit its needs. For example, card may define number of channels to be
+in [1; 8] range, and some particular stream may be limited to [1; 2] only.
+The rule is that the underlying layer must be a subset of the upper layer
+range.
+
+I<COMMON parameters:>
+
+=over 4
+
+=over 4
+
+=item B<sample-rates=RATES>
+
+List of integer values separated by semicolon: sample-rates=8000;22050;44100
+
+=item B<sample-formats=FORMATS>
+
+List of string values separated by semicolon: sample-formats=s16_le;s8;u32_be
+
+Supported formats: s8, u8, s16_le, s16_be, u16_le, u16_be, s24_le, s24_be,
+u24_le, u24_be, s32_le, s32_be, u32_le, u32_be, float_le, float_be,
+float64_le, float64_be, iec958_subframe_le, iec958_subframe_be,
+mu_law, a_law, ima_adpcm, mpeg, gsm
+
+=item B<channels-min=NUMBER>
+
+The minimum amount of channels.
+
+=item B<channels-max=NUMBER>
+
+The maximum amount of channels.
+
+=item B<buffer-size=NUMBER>
+
+The maximum size in octets of the buffer to allocate per stream.
+
+=back
+
+=back
+
+I<CARD specification:>
+
+=over 4
+
+=over 4
+
+=item B<backend=domain-id>
+
+Specify the backend domain name or id, defaults to dom0.
+
+=item B<short-name=STRING>
+
+Short name of the virtual sound card.
+
+=item B<long-name=STRING>
+
+Long name of the virtual sound card.
+
+=back
+
+=back
+
+I<PCM specification:>
+
+=over 4
+
+=over 4
+
+=item B<name=STRING>
+
+Name of the PCM sound device within the virtual sound card.
+
+=back
+
+=back
+
+I<STREAM specification:>
+
+=over 4
+
+=over 4
+
+=item B<id=STRING>
+
+Unique stream identifier.
+
+=item B<type=TYPE>
+
+Stream type: "p" - playback stream, "c" - capture stream.
+
+=back
+
+=back
+
+I<EXAMPLE:>
+
+    vsnd = [
+        ['CARD, short-name=Main, sample-formats=s16_le;s8;u32_be',
+            'PCM, name=Main',
+                'STREAM, id=0, type=p',
+                'STREAM, id=1, type=c, channels-max=2'
+        ],
+        ['CARD, short-name=Second',
+            'PCM, name=Second, buffer-size=1024',
+                'STREAM, id=2, type=p',
+                'STREAM, id=3, type=c'
+        ]
+    ]
+
 =back
 
 =head2 Paravirtualised (PV) Guest Specific Options
diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
index 48da2052cc..90423bf3df 100644
--- a/docs/man/xl.pod.1.in
+++ b/docs/man/xl.pod.1.in
@@ -1492,6 +1492,36 @@ List virtual displays for a domain.
 
 =back
 
+=head2 VSND DEVICES
+
+=over 4
+
+=item B<vsnd-attach> I<domain-id> I<vsnd-item> I<vsnd-item> ...
+
+Creates a new vsnd device in the domain specified by I<domain-id>.
+I<vsnd-item>'s describe the vsnd device to attach, using the same format as the
+B<VSND_ITEM_SPEC> string in the domain config file. See L<xl.cfg> for
+more information.
+
+B<EXAMPLE>
+
+=over 4
+
+xl vsnd-attach DomU 'CARD, short-name=Main, sample-formats=s16_le;s8;u32_be'
+'PCM, name=Main' 'STREAM, id=0, type=p' 'STREAM, id=1, type=c, channels-max=2'
+
+=back
+
+=item B<vsnd-detach> I<domain-id> I<dev-id>
+
+Removes the vsnd device specified by I<dev-id> from the domain specified by 
I<domain-id>.
+
+=item B<vsnd-list> I<domain-id>
+
+List vsnd devices for a domain.
+
+=back
+
 =head1 PCI PASS-THROUGH
 
 =over 4
-- 
2.17.0


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel