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 28, 2004 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.Ss Supported Cards 270Below we include a list of supported codecs/cards. 271If your sound card 272is not listed here, it may be supported by a bridge driver. 273.Bl -tag -width 2m 274.It CS4237, CS4236, CS4232, CS4231 (ISA) 275All these cards work perfectly in full duplex using the MSS mode. 276This chipset is used, among others, on the A/Open AW35 and AW32, on 277some Intel motherboards, and (the CS4231) on some non-PnP cards. 278.Pp 279The CS4232 is reported as buggy in the Voxware documentation but 280I am not sure if this is true. 281On one of my Intel motherboards, 282capture does not work simply because the capture DMA channel is 283not wired to the ISA DMA controller. 284.It Yamaha OPL-SAx (ISA) 285Works perfectly in all modes. 286This chip is used in several PnP cards, 287but also (in non-PnP mode) on motherboards and laptops (e.g., the 288Toshiba Libretto). 289.It OPTi931 (ISA) 290The chip is buggy, but the driver has many workarounds to make it work 291in full duplex because for some time these were the only full duplex 292cards I could find. 293U-law format uses U8 format internally because of 294a bug in the chip. 295.It Trident 4DWave DX/NX (PCI) 296.It ENSONIQ AudioPCI ES1370/1371 (PCI) 297Creative Labs SoundBlaster PCI is supported as well. 298.It ESS Solo-1/1E (PCI) 299.It NeoMagic 256AV/ZX (PCI) 300.El 301.Sh FILES 302The 303.Nm 304drivers may create the following 305device nodes: 306.Pp 307.Bl -tag -width ".Pa /dev/audio%d.%d" -compact 308.It Pa /dev/audio%d.%d 309Sparc-compatible audio device. 310.It Pa /dev/dsp%d.%d 311Digitized voice device. 312.It Pa /dev/dspW%d.%d 313Like 314.Pa /dev/dsp , 315but 16 bits per sample. 316.It Pa /dev/dspr%d.%d 317Should be connected to a record codec. 318.It Pa /dev/sndstat 319Current 320.Nm 321status, including all channels and drivers. 322.El 323.Pp 324The first number in the device node 325represents the unit number of the 326.Nm 327device. 328All 329.Nm 330devices are listed 331in 332.Pa /dev/sndstat . 333Additional messages are sometimes recorded when the 334device is probed and attached, these messages can be viewed with the 335.Xr dmesg 8 336utility. 337.Sh DIAGNOSTICS 338.Bl -diag 339.It ac97: dac not ready 340AC97 codec is not likely to be accompanied with the sound card. 341.It unsupported subdevice XX 342A device node is not created properly. 343.El 344.Sh SEE ALSO 345.Xr snd_csa 4 , 346.Xr snd_gusc 4 , 347.Xr snd_sbc 4 , 348.Xr devfs 5 , 349.Xr loader.conf 5 , 350.Xr dmesg 8 , 351.Xr kldload 8 , 352.Xr sysctl 8 353.Rs 354.%T "The OSS API" 355.%O "http://www.opensound.com/pguide/oss.pdf" 356.Re 357.Sh HISTORY 358The 359.Nm 360device driver first appeared in 361.Fx 2.2.6 362as 363.Nm pcm , 364written by 365.An Luigi Rizzo . 366It was later 367rewritten in 368.Fx 4.0 369by 370.An Cameron Grant . 371The API evolved from the VOXWARE 372standard which later became OSS standard. 373.Sh AUTHORS 374.An -nosplit 375.An Luigi Rizzo Aq luigi@iet.unipi.it 376initially wrote the 377.Nm pcm 378device driver and this manual page. 379.An Cameron Grant Aq gandalf@vilnya.demon.co.uk 380later revised the device driver for 381.Fx 4.0 . 382.An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp 383revised this manual page. 384It was then rewritten for 385.Fx 5.2 . 386.Sh BUGS 387Some features of your cards (e.g., global volume control) might not 388be supported on all devices. 389