1 files changed, 176 insertions, 0 deletions
diff --git a/share/man/man4/snd_hdsp.4 b/share/man/man4/snd_hdsp.4
new file mode 100644
index 000000000000..ca24bcf22cd0
--- /dev/null
+++ b/share/man/man4/snd_hdsp.4
@@ -0,0 +1,176 @@
+.\" Copyright (c) 2012 Ruslan Bukin <br@bsdpad.com>
+.\" Copyright (c) 2024 Florian Walpen <dev@submerge.ch>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd October 28, 2024
+.Dt SND_HDSP 4
+.Os
+.Sh NAME
+.Nm snd_hdsp
+.Nd "RME HDSP bridge device driver"
+.Sh SYNOPSIS
+To compile this driver into the kernel, place the following lines in your
+kernel configuration file:
+.Bd -ragged -offset indent
+.Cd "device sound"
+.Cd "device snd_hdsp"
+.Ed
+.Pp
+Alternatively, to load the driver as a module at boot time, place the
+following line in
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+snd_hdsp_load="YES"
+.Ed
+.Sh DESCRIPTION
+The
+.Nm
+bridge driver allows the generic audio driver
+.Xr sound 4
+to attach to RME HDSP audio devices.
+.Sh HARDWARE
+The
+.Nm
+driver supports the following audio devices:
+.Pp
+.Bl -bullet -compact
+.It
+RME HDSP 9632 (optional AO4S-192 and AIS-192 extension boards)
+.It
+RME HDSP 9652
+.El
+.Pp
+By default, each
+.Xr pcm 4
+device corresponds to a physical port on the sound card.
+For ADAT ports, 8 channel, 4 channel and 2 channel formats are supported.
+The effective number of ADAT channels is 8 channels at single speed
+(32kHz-48kHz) and 4 channels at double speed (64kHz-96kHz).
+Only the HDSP 9632 can operate at quad speed (128kHz-192kHz), ADAT is
+disabled in this mode.
+Depending on sample rate and channel format selected, not all pcm channels can
+be mapped to ADAT channels and vice versa.
+.Sh LOADER TUNABLES
+These settings can be entered at the
+.Xr loader 8
+prompt or in
+.Xr loader.conf 5 .
+.Bl -tag -width indent
+.It Va hw.hdsp.unified_pcm
+If set to 1, all physical ports are combined into one unified pcm device.
+When opened in multi-channel audio software, this makes all ports available
+at the same time, and fully synchronized.
+For resulting channel numbers consult the following table:
+.El
+.Bl -column "Sound Card" "Single Speed" "Double Speed" "Quad Speed"
+.Sy "Sound Card" Ta Sy "Single Speed" Ta Sy "Double Speed" Ta Sy "Quad Speed"
+.It "" Ta "Play | Rec" Ta "Play | Rec" Ta "Play | Rec"
+.It HDSP 9632 Ta " 16  |  16" Ta " 12  |  12" Ta "  8  |   8"
+.It HDSP 9652 Ta " 26  |  26" Ta " 14  |  14" Ta "  -  |   -"
+.El
+.Sh SYSCTL TUNABLES
+These settings and informational values can be accessed at runtime with the
+.Xr sysctl 8
+command.
+If multiple RME HDSP sound cards are installed, each device has a separate
+configuration.
+To adjust the following sysctl identifiers for a specific sound card, insert
+the respective device number in place of
+.Ql 0 .
+.Bl -tag -width indent
+.It Va dev.hdsp.0.sample_rate
+Set a fixed sample rate from 32000, 44100, 48000, up to 192000.
+This is usually required for digital connections (AES, S/PDIF, ADAT).
+The default value of 0 adjusts the sample rate according to pcm device settings.
+.It Va dev.hdsp.0.period
+The number of samples processed per interrupt, from 32, 64, 128, up to 4096.
+Setting a lower value here results in less latency, but increases system load
+due to frequent interrupt processing.
+Extreme values may cause audio gaps and glitches.
+.It Va dev.hdsp.0.clock_list
+Lists possible clock sources to sync with, depending on the hardware model.
+This includes internal and external master clocks as well as incoming digital
+audio signals like AES, S/PDIF and ADAT.
+.It Va dev.hdsp.0.clock_preference
+Select a preferred clock source from the clock list.
+HDSP cards will sync to this clock source when available, but fall back to
+auto-sync with any other digital clock signal they receive.
+Set this to
+.Ql internal
+if the HDSP card should act as master clock.
+.It Va dev.hdsp.0.clock_source
+Shows the actual clock source in use (read only).
+This differs from what is set as clock preference when in auto-sync mode.
+.It Va dev.hdsp.0.sync_status
+Display the current sync status of all external clock sources.
+Status indications are
+.Ql none
+for no signal at all,
+.Ql lock
+for when a valid signal is present, and
+.Ql sync
+for accurately synchronized signals (required for recording digital
+audio).
+.El
+.Pp
+The following tunables are applicable to HDSP 9632 devices only:
+.Bl -tag -width indent
+.It Va dev.hdsp.0.input_level
+Select the sensitivity of the analog line input.
+Available reference levels for the input signal are
+.Ql LowGain ,
+.Ql +4dBu
+and
+.Ql -10dBV .
+.It Va dev.hdsp.0.output_level
+Select the gain level of the analog line output.
+Available reference levels for the output signal are
+.Ql HighGain ,
+.Ql +4dBu
+and
+.Ql -10dBV .
+.It Va dev.hdsp.0.phones_level
+Adjust the gain level of the phones output, separately from the analog line
+output.
+The signal can be lowered by 6 or 12 dB.
+.El
+.Pp
+Where appropriate these sysctl values are modeled after official RME software on
+other platforms, and adopt their terminology.
+Consult the RME user manuals for additional information.
+.Sh SEE ALSO
+.Xr sound 4
+.Sh HISTORY
+The
+.Nm
+device driver first appeared in
+.Fx 15.0 .
+.Sh AUTHORS
+.An -nosplit
+Based on
+.Xr snd_hdspe 4
+originally written by
+.An Ruslan Bukin <br@bsdpad.com> .
+All adaptation to HDSP cards by
+.An Florian Walpen <dev@submerge.ch> .