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