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