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