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