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 August 17, 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 prefered 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 159that 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 276CS4231, CS4232, CS4236, CS4237 (ISA) 277.It 278Creative Labs SoundBlaster PCI 279.It 280Intel 443MX, 810, 815, and 815E integrated sound devices 281.It 282MSS/WSS Compatible DSPs 283.It 284OPTi931/82C931 (ISA) 285.It 286Yamaha OPL-SAx (ISA) 287.El 288.Sh FILES 289The 290.Nm 291drivers may create the following 292device nodes: 293.Pp 294.Bl -tag -width ".Pa /dev/audio%d.%d" -compact 295.It Pa /dev/audio%d.%d 296Sparc-compatible audio device. 297.It Pa /dev/dsp%d.%d 298Digitized voice device. 299.It Pa /dev/dspW%d.%d 300Like 301.Pa /dev/dsp , 302but 16 bits per sample. 303.It Pa /dev/dspr%d.%d 304Should be connected to a record codec. 305.It Pa /dev/sndstat 306Current 307.Nm 308status, including all channels and drivers. 309.El 310.Pp 311The first number in the device node 312represents the unit number of the 313.Nm 314device. 315All 316.Nm 317devices are listed 318in 319.Pa /dev/sndstat . 320Additional messages are sometimes recorded when the 321device is probed and attached, these messages can be viewed with the 322.Xr dmesg 8 323utility. 324.Sh DIAGNOSTICS 325.Bl -diag 326.It ac97: dac not ready 327AC97 codec is not likely to be accompanied with the sound card. 328.It unsupported subdevice XX 329A device node is not created properly. 330.El 331.Sh SEE ALSO 332.Xr snd_ad1816 4 , 333.Xr snd_als4000 4 , 334.Xr snd_audiocs 4 , 335.Xr snd_cmi 4 , 336.Xr snd_cs4281 4 , 337.Xr snd_csa 4 , 338.Xr snd_ds1 4 , 339.Xr snd_emu10k1 4 , 340.Xr snd_es137x 4 , 341.Xr snd_ess 4 , 342.Xr snd_fm801 4 , 343.Xr snd_gusc 4 , 344.Xr snd_ich 4 , 345.Xr snd_maestro 4 , 346.Xr snd_maestro3 4 , 347.Xr snd_neomagic 4 , 348.Xr snd_sbc 4 , 349.Xr snd_solo 4 , 350.Xr snd_t4dwave 4 , 351.Xr snd_uaudio 4 , 352.Xr snd_via8233 4 , 353.Xr snd_via82c686 4 , 354.Xr snd_vibes 4 , 355.Xr devfs 5 , 356.Xr loader.conf 5 , 357.Xr dmesg 8 , 358.Xr kldload 8 , 359.Xr sysctl 8 360.Rs 361.%T "The OSS API" 362.%O "http://www.opensound.com/pguide/oss.pdf" 363.Re 364.Sh HISTORY 365The 366.Nm 367device driver first appeared in 368.Fx 2.2.6 369as 370.Nm pcm , 371written by 372.An Luigi Rizzo . 373It was later 374rewritten in 375.Fx 4.0 376by 377.An Cameron Grant . 378The API evolved from the VOXWARE 379standard which later became OSS standard. 380.Sh AUTHORS 381.An -nosplit 382.An Luigi Rizzo Aq luigi@iet.unipi.it 383initially wrote the 384.Nm pcm 385device driver and this manual page. 386.An Cameron Grant Aq gandalf@vilnya.demon.co.uk 387later revised the device driver for 388.Fx 4.0 . 389.An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp 390revised this manual page. 391It was then rewritten for 392.Fx 5.2 . 393.Sh BUGS 394Some features of your cards (e.g., global volume control) might not 395be supported on all devices. 396