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 29, 2006 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 39To compile this driver into the kernel, place the following line in your 40kernel configuration file: 41.Bd -ragged -offset indent 42.Cd "device sound" 43.Ed 44.Pp 45Non-PnP sound cards require the following lines in 46.Xr device.hints 5 : 47.Bd -literal -offset indent 48hint.pcm.0.at="isa" 49hint.pcm.0.irq="5" 50hint.pcm.0.drq="1" 51hint.pcm.0.flags="0x0" 52.Ed 53.Sh DESCRIPTION 54.Bf -emphasis 55Note: There exists some ambiguity in the naming at the moment 56.Pq Nm sound , pcm , snd . 57It will be resolved soon by renaming 58.Cd "device sound" 59to 60.Cd "device snd" , 61and doing associated changes. 62.Ef 63.Pp 64The 65.Nm 66driver provides support for 67.Tn PCM 68audio play and capture. 69This driver also supports various 70.Tn PCI , 71.Tn ISA , 72.Tn WSS/MSS 73compatible 74sound cards, AC97 mixer and High Definition Audio. 75Once the 76.Nm 77driver attaches, supported devices provide audio record and 78playback channels. 79The 80.Fx 81sound system provides dynamic mixing 82.Dq VCHAN 83and rate conversion 84.Dq soft formats . 85True full duplex operation is available on most sound cards. 86.Pp 87If the sound card is supported by a bridge driver, the 88.Nm 89driver works in conjunction with the bridge driver. 90.Pp 91Apart from the usual parameters, the flags field is used to specify 92the secondary 93.Tn DMA 94channel (generally used for capture in full duplex cards). 95Flags are set to 0 for cards not using a secondary 96.Tn DMA 97channel, or to 0x10 + C to specify channel C. 98.Pp 99The driver does its best to recognize the installed hardware and drive 100it correctly so the user is not required to add several lines in 101.Pa /boot/device.hints . 102For 103.Tn PCI 104and 105.Tn ISA 106.Tn PnP 107cards this is actually easy 108since they identify themselves. 109For legacy 110.Tn ISA 111cards, the driver looks for 112.Tn MSS 113cards at addresses 0x530 and 0x604 (unless overridden 114in 115.Pa /boot/device.hints ) . 116.Ss Boot Variables 117In general, the module 118.Pa snd_foo 119corresponds to 120.Cd "device snd_foo" 121and can be 122loaded by the boot 123.Xr loader 8 124via 125.Xr loader.conf 5 126or from the command line using the 127.Xr kldload 8 128utility. 129Options which can be specified in 130.Pa /boot/loader.conf 131include: 132.Bl -tag -width ".Va snd_emu10k1_load" -offset indent 133.It Va snd_driver_load 134.Pq Dq Li NO 135If set to 136.Dq Li YES , 137this option loads all available drivers. 138.It Va snd_emu10k1_load 139.Pq Dq Li NO 140If set to 141.Dq Li YES , 142only the SoundBlaster 5.1 driver and dependent modules will be loaded. 143.It Va snd_foo_load 144.Pq Dq Li NO 145If set to 146.Dq Li YES , 147load driver for card/chipset foo. 148.El 149.Pp 150To define default values for the different mixer channels, 151set the channel to the preferred value using hints, e.g.: 152.Va hint.pcm.0.line Ns = Ns Qq Li 0 . 153This will mute the input channel per default. 154.Ss VCHANs 155Each device can optionally support more playback channels 156than physical hardware provides by using 157.Dq virtual channels 158or 159.Tn VCHANs . 160.Tn VCHAN 161options can be configured via the 162.Xr sysctl 8 163interface but can only be manipulated while the device is inactive. 164.Ss Runtime Configuration 165There are a number of 166.Xr sysctl 8 167variables available. 168.Va hw.snd.* 169tunables are global settings and 170.Va dev.pcm.* 171are device specific. 172.Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent 173.It Va hw.snd.latency_profile 174Define sets of buffering latency conversion tables for the 175.Va hw.snd.latency 176tunable. 177A value of 0 will use a low and aggressive latency profile which can result 178in possible underruns if the application cannot keep up with a rapid irq 179rate, especially during high workload. 180The default value is 1, which is considered a moderate/safe latency profile. 181.It Va hw.snd.latency 182Configure the buffering latency. 183Only affects applications that do not explicitly request 184blocksize / fragments. 185This tunable provides finer granularity than the 186.Va hw.snd.latency_profile 187tunable. 188Possible values range between 0 (lowest latency) and 10 (highest latency). 189.It Va hw.snd.report_soft_formats 190Controls the internal format conversion if it is 191available transparently to the application software. 192When disabled or not available, the application will 193only be able to select formats the device natively supports. 194.It Va hw.snd.feeder_rate_round 195Sample rate rounding threshold, to avoid large prime division at the 196cost of accuracy. 197All requested sample rates will be rounded to the nearest threshold value. 198Possible values range between 0 (disabled) and 500. 199Default is 25. 200.It Va hw.snd.feeder_rate_max 201Maximum allowable sample rate. 202.It Va hw.snd.feeder_rate_min 203Minimum allowable sample rate. 204.It Va hw.snd.verbose 205Level of verbosity for the 206.Pa /dev/sndstat 207device. 208Higher values include more output and the highest level, 209four, should be used when reporting problems. 210Other options include: 211.Bl -tag -width 2n 212.It 0 213Installed devices and their allocated bus resources. 214.It 1 215The number of playback, record, virtual channels, and 216flags per device. 217.It 2 218Channel information per device including the channel's 219current format, speed, and pseudo device statistics such as 220buffer overruns and buffer underruns. 221.It 3 222File names and versions of the currently loaded sound modules. 223.It 4 224Various messages intended for debugging. 225.El 226.It Va hw.snd.maxautovchans 227Global 228.Tn VCHAN 229setting that only affects devices with only one playback channel available. 230The sound system will dynamically create up this many 231.Tn VCHANs . 232Set to 233.Dq 0 234if no 235.Tn VCHANS 236are desired. 237Maximum value is 255. 238.It Va hw.snd.default_unit 239Default sound card for systems with multiple sound cards. 240When using 241.Xr devfs 5 , 242the default device for 243.Pa /dev/dsp . 244Equivalent to a symlink from 245.Pa /dev/dsp 246to 247.Pa /dev/dsp Ns Va ${hw.snd.default_unit} . 248.It Va dev.pcm.%d.vchans 249The current number of 250.Tn VCHANs 251allocated per device. 252This can be set to preallocate a certain number of 253.Tn VCHANs . 254Setting this value to 255.Dq 0 256will disable 257.Tn VCHANs 258for this device. 259.It Va dev.pcm.%d.vchanrate 260Sample rate speed for 261.Tn VCHAN 262mixing. 263All playback paths will be converted to this sample rate before the mixing 264process begins. 265.It Va dev.pcm.%d.vchanformat 266Format for 267.Tn VCHAN 268mixing. 269All playback paths will be converted to this format before the mixing 270process begins. 271.It Va dev.pcm.%d.polling 272Experimental polling mode support where the driver operates by querying the 273device state on each tick using a 274.Xr callout 9 275mechanism. 276Disabled by default and currently only available for a few device drivers. 277.El 278.Ss Recording Channels 279On devices that have more than one recording source (ie: mic and line), 280there is a corresponding 281.Pa /dev/dsp%d.r%d 282device. 283.Ss Statistics 284Channel statistics are only kept while the device is open. 285So with situations involving overruns and underruns, consider the output 286while the errant application is open and running. 287.Ss IOCTL Support 288The driver supports most of the 289.Tn OSS 290.Fn ioctl 291functions, and most applications work unmodified. 292A few differences exist, while memory mapped playback is 293supported natively and in 294.Tn Linux 295emulation, memory mapped recording is 296not due to 297.Tn VM 298system design. 299As a consequence, some applications may need to be recompiled 300with a slightly modified audio module. 301See 302.In sys/soundcard.h 303for a complete list of the supported 304.Fn ioctl 305functions. 306.Sh FILES 307The 308.Nm 309drivers may create the following 310device nodes: 311.Pp 312.Bl -tag -width ".Pa /dev/audio%d.%d" -compact 313.It Pa /dev/audio%d.%d 314Sparc-compatible audio device. 315.It Pa /dev/dsp%d.%d 316Digitized voice device. 317.It Pa /dev/dspW%d.%d 318Like 319.Pa /dev/dsp , 320but 16 bits per sample. 321.It Pa /dev/dsp%d.p%d 322Playback channel. 323.It Pa /dev/dsp%d.r%d 324Record channel. 325.It Pa /dev/dsp%d.v%d 326Virtual channel. 327.It Pa /dev/sndstat 328Current 329.Nm 330status, including all channels and drivers. 331.El 332.Pp 333The first number in the device node 334represents the unit number of the 335.Nm 336device. 337All 338.Nm 339devices are listed 340in 341.Pa /dev/sndstat . 342Additional messages are sometimes recorded when the 343device is probed and attached, these messages can be viewed with the 344.Xr dmesg 8 345utility. 346.Sh DIAGNOSTICS 347.Bl -diag 348.It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead 349The hardware does not generate interrupts to serve incoming (play) 350or outgoing (record) data. 351.It unsupported subdevice XX 352A device node is not created properly. 353.El 354.Sh SEE ALSO 355.Xr snd_ad1816 4 , 356.Xr snd_als4000 4 , 357.Xr snd_atiixp 4 , 358.Xr snd_audiocs 4 , 359.Xr snd_cmi 4 , 360.Xr snd_cs4281 4 , 361.Xr snd_csa 4 , 362.Xr snd_ds1 4 , 363.Xr snd_emu10k1 4 , 364.Xr snd_emu10kx 4 , 365.Xr snd_envy24 4 , 366.Xr snd_envy24ht 4 , 367.Xr snd_es137x 4 , 368.Xr snd_ess 4 , 369.Xr snd_fm801 4 , 370.Xr snd_gusc 4 , 371.Xr snd_hda 4 , 372.Xr snd_ich 4 , 373.Xr snd_maestro 4 , 374.Xr snd_maestro3 4 , 375.Xr snd_mss 4 , 376.Xr snd_neomagic 4 , 377.Xr snd_sbc 4 , 378.Xr snd_solo 4 , 379.Xr snd_spicds 4 , 380.Xr snd_t4dwave 4 , 381.Xr snd_uaudio 4 , 382.Xr snd_via8233 4 , 383.Xr snd_via82c686 4 , 384.Xr snd_vibes 4 , 385.Xr devfs 5 , 386.Xr device.hints 5 , 387.Xr loader.conf 5 , 388.Xr dmesg 8 , 389.Xr kldload 8 , 390.Xr sysctl 8 391.Rs 392.%T "The OSS API" 393.%O "http://www.opensound.com/pguide/oss.pdf" 394.Re 395.Sh HISTORY 396The 397.Nm 398device driver first appeared in 399.Fx 2.2.6 400as 401.Nm pcm , 402written by 403.An Luigi Rizzo . 404It was later 405rewritten in 406.Fx 4.0 407by 408.An Cameron Grant . 409The API evolved from the VOXWARE 410standard which later became OSS standard. 411.Sh AUTHORS 412.An -nosplit 413.An Luigi Rizzo Aq luigi@iet.unipi.it 414initially wrote the 415.Nm pcm 416device driver and this manual page. 417.An Cameron Grant Aq gandalf@vilnya.demon.co.uk 418later revised the device driver for 419.Fx 4.0 . 420.An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp 421revised this manual page. 422It was then rewritten for 423.Fx 5.2 . 424.Sh BUGS 425Some features of your sound card (e.g., global volume control) might not 426be supported on all devices. 427