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