1.\" 2.\" Copyright (c) 1998, Luigi Rizzo 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd November 28, 2005 29.Dt SOUND 4 30.Os 31.Sh NAME 32.Nm sound , 33.Nm pcm , 34.Nm snd 35.Nd 36.Fx 37PCM audio device infrastructure 38.Sh SYNOPSIS 39For a card with bridge driver support, and a PnP card: 40.Cd "device sound" 41.Pp 42For a card without bridge driver support, and a non-PnP card, 43the following lines may be required in 44.Pa /boot/device.hints : 45.Cd hint.pcm.0.at="isa" 46.Cd hint.pcm.0.irq="5" 47.Cd hint.pcm.0.drq="1" 48.Cd hint.pcm.0.flags="0x0" 49.Sh DESCRIPTION 50.Bf -emphasis 51Note: There exists some ambiguity in the naming at the moment 52.Pq Nm sound , pcm , snd . 53It will be resolved soon by renaming 54.Cd "device sound" 55to 56.Cd "device snd" , 57and doing associated changes. 58.Ef 59.Pp 60The 61.Nm 62driver provides support for 63.Tn PCM 64audio play and capture. 65This driver also supports various 66.Tn PCI , 67.Tn WSS/MSS 68compatible, 69.Tn ISA 70sound cards, and AC97 mixer. 71Once the 72.Nm 73driver attaches, supported devices provide audio record and 74playback channels. 75The 76.Fx 77sound system provides dynamic mixing 78.Dq VCHAN 79and rate conversion 80.Dq soft formats . 81True full duplex operation is available on most cards. 82.Pp 83If the sound card is supported by a bridge driver, the 84.Nm 85driver works in conjunction with the bridge driver. 86.Pp 87Apart from the usual parameters, the flags field is used to specify 88the secondary 89.Tn DMA 90channel (generally used for capture in full duplex cards). 91Flags are set to 0 for cards not using a secondary 92.Tn DMA 93channel, or to 0x10 + C to specify channel C. 94.Pp 95The driver works best with 96.Tn WSS/MSS 97cards, which have a very clean 98architecture and an orthogonal set of features. 99They also happen to be 100among the cheapest audio cards on the market. 101.Pp 102The driver does its best to recognize the installed hardware and drive 103it correctly so the user is not required to add several lines in 104.Pa /boot/device.hints . 105For 106.Tn PCI 107and 108.Tn ISA 109.Tn PnP 110cards this is actually easy 111since they identify themselves. 112For legacy 113.Tn ISA 114cards, the driver looks for 115.Tn MSS 116cards at addresses 0x530 and 0x604 (unless overridden 117in 118.Pa /boot/device.hints ) . 119.Ss Boot Variables 120In general, the module 121.Pa snd_foo 122corresponds to 123.Cd "device snd_foo" 124and can be 125loaded by the boot 126.Xr loader 8 127via 128.Xr loader.conf 5 129or from the command line using the 130.Xr kldload 8 131utility. 132Options which can be specified in 133.Pa /boot/loader.conf 134include: 135.Bl -tag -width ".Va snd_emu10k1_load" -offset indent 136.It Va snd_driver_load 137.Pq Dq Li NO 138If set to 139.Dq Li YES , 140this option loads all available drivers. 141.It Va snd_emu10k1_load 142.Pq Dq Li NO 143If set to 144.Dq Li YES , 145only the SoundBlaster 5.1 driver and dependent modules will be loaded. 146.It Va snd_foo_load 147.Pq Dq Li NO 148If set to 149.Dq Li YES , 150load driver for card/chipset foo. 151.El 152.Pp 153To define default values for the different mixer channels, 154set the channel to the preferred value using hints, e.g.: 155.Va hint.pcm.0.line Ns = Ns Qq Li 0 . 156This will mute the input channel per default. 157.Ss VCHANs 158Each device can optionally support more playback channels 159than physical hardware provides by using 160.Dq virtual channels 161or 162.Tn VCHANs . 163.Tn VCHAN 164options can be configured via the 165.Xr sysctl 8 166interface but can only be manipulated while the device is inactive. 167.Ss Runtime Configuration 168The following 169.Xr sysctl 8 170variables are available: 171.Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent 172.It Va hw.snd.pcm%d.buffersize 173Configure the amount of 174.Tn DMA 175bufferspace available for a device. 176.It Va hw.snd.targetirqrate 177Set the default block size such that continuous 178playback will achieve this 179.Tn IRQ 180rate. 181This value can be tuned to improve application performance. 182Increase this value when the sound lags and decrease 183it if sound stutters or breaks up. 184.It Va hw.snd.unit 185When using 186.Xr devfs 5 , 187the default device for 188.Pa /dev/dsp . 189Equivalent to a symlink from 190.Pa /dev/dsp 191to 192.Pa /dev/dsp Ns Va ${hw.snd.unit} . 193.It Va hw.snd.report_soft_formats 194Controls the internal format conversion if it is 195available transparently to the application software. 196When disabled or not available, the application will 197only be able to select formats the device natively supports. 198.It Va hw.snd.verbose 199Level of verbosity for the 200.Pa /dev/sndstat 201device. 202Higher values include more output and the highest level, 203three, should be used when reporting problems. 204Other options include: 205.Bl -tag -width 2n 206.It 0 207Installed devices and their allocated bus resources. 208.It 1 209The number of playback, record, virtual channels, and 210flags per device. 211.It 2 212Channel information per device including the channel's 213current format, speed, and pseudo device statistics such as 214buffer overruns and buffer underruns. 215.It 3 216File names and versions of the currently sound loaded modules. 217.El 218.It Va hw.snd.maxautovchans 219Global 220.Tn VCHAN 221setting that only affects devices that have only one playback channel. 222The sound system will dynamically create up this many 223.Tn VCHANs . 224Set to 225.Dq 0 226if no 227.Tn VCHANS 228are desired. 229.It Va hw.snd.pcm%d.vchans 230The current number of 231.Tn VCHANs 232allocated per device. 233This can be set to preallocate a certain number of 234.Tn VCHANs . 235Setting this value to 236.Dq 0 237will disable 238.Tn VCHANs 239for this device. 240.El 241.Ss Recording Channels 242On devices that have more than one recording source (ie: mic and line), 243there is a corresponding 244.Pa /dev/dspr%d.%d 245device. 246.Ss Statistics 247Channel statistics are only kept while the device is open. 248So with situations involving overruns and underruns, consider the output 249while the errant application is open and running. 250.Ss IOCTL Support 251The driver supports most of the 252.Tn OSS 253.Fn ioctl 254functions, and most applications work unmodified. 255A few differences exist, while memory mapped playback is 256supported natively and in 257.Tn Linux 258emulation, memory mapped recording is 259not due to 260.Tn VM 261system design. 262As a consequence, some applications may need to be recompiled 263with a slightly modified audio module. 264See 265.In sys/soundcard.h 266for a complete list of the supported 267.Fn ioctl 268functions. 269.Sh HARDWARE 270The 271.Nm 272driver supports the following sound cards: 273.Pp 274.Bl -bullet -compact 275.It 276Creative Labs SoundBlaster PCI 277.It 278Intel 443MX, 810, 815, and 815E integrated sound devices 279.El 280.Sh FILES 281The 282.Nm 283drivers may create the following 284device nodes: 285.Pp 286.Bl -tag -width ".Pa /dev/audio%d.%d" -compact 287.It Pa /dev/audio%d.%d 288Sparc-compatible audio device. 289.It Pa /dev/dsp%d.%d 290Digitized voice device. 291.It Pa /dev/dspW%d.%d 292Like 293.Pa /dev/dsp , 294but 16 bits per sample. 295.It Pa /dev/dspr%d.%d 296Should be connected to a record codec. 297.It Pa /dev/sndstat 298Current 299.Nm 300status, including all channels and drivers. 301.El 302.Pp 303The first number in the device node 304represents the unit number of the 305.Nm 306device. 307All 308.Nm 309devices are listed 310in 311.Pa /dev/sndstat . 312Additional messages are sometimes recorded when the 313device is probed and attached, these messages can be viewed with the 314.Xr dmesg 8 315utility. 316.Sh DIAGNOSTICS 317.Bl -diag 318.It ac97: dac not ready 319AC97 codec is not likely to be accompanied with the sound card. 320.It unsupported subdevice XX 321A device node is not created properly. 322.El 323.Sh SEE ALSO 324.Xr snd_ad1816 4 , 325.Xr snd_als4000 4 , 326.Xr snd_atiixp 4 , 327.Xr snd_audiocs 4 , 328.Xr snd_cmi 4 , 329.Xr snd_cs4281 4 , 330.Xr snd_csa 4 , 331.Xr snd_ds1 4 , 332.Xr snd_emu10k1 4 , 333.Xr snd_es137x 4 , 334.Xr snd_ess 4 , 335.Xr snd_fm801 4 , 336.Xr snd_gusc 4 , 337.Xr snd_ich 4 , 338.Xr snd_maestro 4 , 339.Xr snd_maestro3 4 , 340.Xr snd_mss 4 , 341.Xr snd_neomagic 4 , 342.Xr snd_sbc 4 , 343.Xr snd_solo 4 , 344.Xr snd_t4dwave 4 , 345.Xr snd_uaudio 4 , 346.Xr snd_via8233 4 , 347.Xr snd_via82c686 4 , 348.Xr snd_vibes 4 , 349.Xr devfs 5 , 350.Xr loader.conf 5 , 351.Xr dmesg 8 , 352.Xr kldload 8 , 353.Xr sysctl 8 354.Rs 355.%T "The OSS API" 356.%O "http://www.opensound.com/pguide/oss.pdf" 357.Re 358.Sh HISTORY 359The 360.Nm 361device driver first appeared in 362.Fx 2.2.6 363as 364.Nm pcm , 365written by 366.An Luigi Rizzo . 367It was later 368rewritten in 369.Fx 4.0 370by 371.An Cameron Grant . 372The API evolved from the VOXWARE 373standard which later became OSS standard. 374.Sh AUTHORS 375.An -nosplit 376.An Luigi Rizzo Aq luigi@iet.unipi.it 377initially wrote the 378.Nm pcm 379device driver and this manual page. 380.An Cameron Grant Aq gandalf@vilnya.demon.co.uk 381later revised the device driver for 382.Fx 4.0 . 383.An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp 384revised this manual page. 385It was then rewritten for 386.Fx 5.2 . 387.Sh BUGS 388Some features of your cards (e.g., global volume control) might not 389be supported on all devices. 390