git: 5960ab73d865 - main - snd_uaudio.4: document sysctls

The branch main has been updated by christos:

URL: https://cgit.FreeBSD.org/src/commit/?id=5960ab73d865b59bfa7d7fd3bd49a6f7d730ef83

commit 5960ab73d865b59bfa7d7fd3bd49a6f7d730ef83
Author:     Christos Margiolis <christos@FreeBSD.org>
AuthorDate: 2024-02-12 11:06:00 +0000
Commit:     Christos Margiolis <christos@FreeBSD.org>
CommitDate: 2024-02-12 11:07:51 +0000

    snd_uaudio.4: document sysctls
    
    Sponsored by:   The FreeBSD Foundation
    MFC after:      2 weeks
    Reviewed by:    dev_submerge.ch
    Differential Revision:  https://reviews.freebsd.org/D43649
---
 share/man/man4/snd_uaudio.4 | 81 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 78 insertions(+), 3 deletions(-)

diff --git a/share/man/man4/snd_uaudio.4 b/share/man/man4/snd_uaudio.4
index 04dc10ccaa25..b6a6c06a2312 100644
--- a/share/man/man4/snd_uaudio.4
+++ b/share/man/man4/snd_uaudio.4
@@ -57,12 +57,88 @@ A USB audio device consists of a number of components: input terminals (e.g.\&
 USB digital input), output terminals (e.g.\& speakers), and a number of units
 in between (e.g.\& volume control).
 .Pp
+If the device supports multiple configurations, and there have been no
+user-supplied values specified through the
+.Xr sysctl 8
+interface, the driver will select the best matching configuration supported by
+the device during attach.
+"Best" means the configuration with the most channels and highest quality in
+sample rate and sample size.
+.Pp
 Refer to the
 .Ql USB Audio Class Specification
 for more information.
+.Sh SYSCTL VARIABLES
+The following settings can be entered at the
+.Xr loader 8
+prompt or in
+.Xr loader.conf 5
+and can also be changed at runtime with the
+.Xr sysctl 8
+command.
+For a change to take effect during runtime, the device has to be re-attached.
+.Bl -tag -width indent
+.It Va hw.usb.uaudio.buffer_ms
+Period of audio data processed at once, in milliseconds, from 1 to 8 (default
+is 4).
+Lower values mean less latency, but this can result in audible gaps due to
+frequent CPU wakeups.
+.It Va hw.usb.uaudio.default_bits
+Preferred sample size in bits, from 0 to 32 (default is 0).
+A value of 0 sets the sample size to the maximum supported sample size.
+.Pp
+Set this to select a smaller sample size if the device supports multiple sample
+sizes.
+.It Va hw.usb.uaudio.default_channels
+Preferred number of sample channels, from 0 to 64 (default is 0).
+USB 1.1 devices are limited to 4 channels due to bandwidth constraints, unless
+a higher value is explicitly requested.
+A value of 0 sets the sample channels to the maximum supported channel number.
+.Pp
+Set this to select a smaller channel number if the device supports multiple
+channel configurations.
+.It Va hw.usb.uaudio.default_rate
+Preferred sample rate in Hz (default is 0).
+If set to 0, the device's highest supported sample rate will be used.
+.Pp
+Note that if VCHANs are enabled, the sample rate will be overridden by
+.Pa dev.pcm.%d.[play|rec].vchanrate
+(see
+.Xr sound 4 ) ,
+which can also be used to adjust the sample rate during runtime.
+.Pp
+If
+.Pa hw.usb.uaudio.default_rate
+is non-zero,
+.Pa dev.pcm.%d.[play|rec].vchanrate
+will use it as its maximum allowed value.
+.It Va hw.usb.uaudio.handle_hid
+Let
+.Nm
+handle HID volume keys, if any (default is 1).
+.Bl -tag -width 2n
+.It 0
+Disabled.
+.It 1
+Enabled.
+.El
+.El
+.Pp
+If
+.Xr usb 4
+has been compiled with
+.Va USB_DEBUG
+on, the following setting is also available:
+.Bl -tag -width indent
+.It Va hw.usb.uaudio.debug
+Debug output level (default is 0).
+.El
 .Sh SEE ALSO
 .Xr sound 4 ,
-.Xr usb 4
+.Xr usb 4 ,
+.Xr loader.conf 5 ,
+.Xr loader 8 ,
+.Xr sysctl 8
 .Rs
 .%T "USB Audio Class Specifications"
 .%U http://www.usb.org/developers/docs/devclass_docs/
@@ -98,8 +174,7 @@ sysctls.
 .Pp
 The PCM framework in
 .Fx
-currently doesn't support the full set of USB audio mixer
-controls.
+currently does not support the full set of USB audio mixer controls.
 Some mixer controls are only available as
 .Va dev.pcm.%d.mixer
 sysctls.