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