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.50 2006/11/29 17:07:02 joel Exp $ 27.\" $DragonFly: src/share/man/man4/pcm.4,v 1.6 2007/01/04 21:47:00 corecode Exp $ 28.\" 29.Dd November 29, 2006 30.Dt SOUND 4 31.Os 32.Sh NAME 33.Nm sound , 34.Nm pcm , 35.Nm snd 36.Nd 37.Fx 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 146There are a number of 147.Xr sysctl 8 148variables available. 149.Va hw.snd.* 150tunables are global settings and 151.Va dev.pcm.* 152are device specific. 153.Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent 154.It Va hw.snd.latency_profile 155Define sets of buffering latency conversion tables for the 156.Va hw.snd.latency 157tunable. 158A value of 0 will use a low and aggressive latency profile which can result 159in possible underruns if the application cannot keep up with a rapid irq 160rate, especially during high workload. 161The default value is 1, which is considered a moderate/safe latency profile. 162.It Va hw.snd.latency 163Configure the buffering latency. 164Only affects applications that do not explicitly request 165blocksize / fragments. 166This tunable provides finer granularity than the 167.Va hw.snd.latency_profile 168tunable. 169Possible values range between 0 (lowest latency) and 10 (highest latency). 170.It Va hw.snd.report_soft_formats 171Controls the internal format conversion if it is 172available transparently to the application software. 173When disabled or not available, the application will 174only be able to select formats the device natively supports. 175.It Va hw.snd.feeder_rate_round 176Sample rate rounding threshold, to avoid large prime division at the 177cost of accuracy. 178All requested sample rates will be rounded to the nearest threshold value. 179Possible values range between 0 (disabled) and 500. 180Default is 25. 181.It Va hw.snd.feeder_rate_max 182Maximum allowable sample rate. 183.It Va hw.snd.feeder_rate_min 184Minimum allowable sample rate. 185.It Va hw.snd.verbose 186Level of verbosity for the 187.Pa /dev/sndstat 188device. 189Higher values include more output and the highest level, 190four, should be used when reporting problems. 191Other options include: 192.Bl -tag -width 2n 193.It 0 194Installed devices and their allocated bus resources. 195.It 1 196The number of playback, record, virtual channels, and 197flags per device. 198.It 2 199Channel information per device including the channel's 200current format, speed, and pseudo device statistics such as 201buffer overruns and buffer underruns. 202.It 3 203File names and versions of the currently loaded sound modules. 204.It 4 205Various messages intended for debugging. 206.El 207.It Va hw.snd.maxautovchans 208Global 209.Tn VCHAN 210setting that only affects devices with only one playback channel available. 211The sound system will dynamically create up this many 212.Tn VCHANs . 213Set to 214.Dq 0 215if no 216.Tn VCHANS 217are desired. 218Maximum value is 255. 219.It Va hw.snd.default_unit 220Default sound card for systems with multiple sound cards. 221When using 222.Xr devfs 5 , 223the default device for 224.Pa /dev/dsp . 225Equivalent to a symlink from 226.Pa /dev/dsp 227to 228.Pa /dev/dsp Ns Va ${hw.snd.default_unit} . 229.It Va dev.pcm.%d.vchans 230The current number of 231.Tn VCHANs 232allocated per device. 233This can be set to preallocate a certain number of 234.Tn VCHANs . 235Setting this value to 236.Dq 0 237will disable 238.Tn VCHANs 239for this device. 240.It Va dev.pcm.%d.vchanrate 241Sample rate speed for 242.Tn VCHAN 243mixing. 244All playback paths will be converted to this sample rate before the mixing 245process begins. 246.It Va dev.pcm.%d.vchanformat 247Format for 248.Tn VCHAN 249mixing. 250All playback paths will be converted to this format before the mixing 251process begins. 252.It Va dev.pcm.%d.polling 253Experimental polling mode support where the driver operates by querying the 254device state on each tick using a 255.Xr callout 9 256mechanism. 257Disabled by default and currently only available for a few device drivers. 258.El 259.Ss Recording Channels 260On devices that have more than one recording source (ie: mic and line), 261there is a corresponding 262.Pa /dev/dsp%d.r%d 263device. 264.Ss Statistics 265Channel statistics are only kept while the device is open. 266So with situations involving overruns and underruns, consider the output 267while the errant application is open and running. 268.Ss IOCTL Support 269The driver supports most of the 270.Tn OSS 271.Fn ioctl 272functions, and most applications work unmodified. 273A few differences exist, while memory mapped playback is 274supported natively and in 275.Tn Linux 276emulation, memory mapped recording is 277not due to 278.Tn VM 279system design. 280As a consequence, some applications may need to be recompiled 281with a slightly modified audio module. 282See 283.In sys/soundcard.h 284for a complete list of the supported 285.Fn ioctl 286functions. 287.Sh FILES 288The 289.Nm 290drivers may create the following 291device nodes: 292.Pp 293.Bl -tag -width ".Pa /dev/audio%d.%d" -compact 294.It Pa /dev/audio%d.%d 295Sparc-compatible audio device. 296.It Pa /dev/dsp%d.%d 297Digitized voice device. 298.It Pa /dev/dspW%d.%d 299Like 300.Pa /dev/dsp , 301but 16 bits per sample. 302.It Pa /dev/dsp%d.p%d 303Playback channel. 304.It Pa /dev/dsp%d.r%d 305Record channel. 306.It Pa /dev/dsp%d.v%d 307Virtual channel. 308.It Pa /dev/sndstat 309Current 310.Nm 311status, including all channels and drivers. 312.El 313.Pp 314The first number in the device node 315represents the unit number of the 316.Nm 317device. 318All 319.Nm 320devices are listed 321in 322.Pa /dev/sndstat . 323Additional messages are sometimes recorded when the 324device is probed and attached, these messages can be viewed with the 325.Xr dmesg 8 326utility. 327.Sh DIAGNOSTICS 328.Bl -diag 329.It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead 330The hardware does not generate interrupts to serve incoming (play) 331or outgoing (record) data. 332.It unsupported subdevice XX 333A device node is not created properly. 334.El 335.Sh SEE ALSO 336.Xr snd_ad1816 4 , 337.Xr snd_als4000 4 , 338.Xr snd_atiixp 4 , 339.Xr snd_audiocs 4 , 340.Xr snd_cmi 4 , 341.Xr snd_cs4281 4 , 342.Xr snd_csa 4 , 343.Xr snd_ds1 4 , 344.Xr snd_emu10k1 4 , 345.Xr snd_emu10kx 4 , 346.Xr snd_envy24 4 , 347.Xr snd_envy24ht 4 , 348.Xr snd_es137x 4 , 349.Xr snd_ess 4 , 350.Xr snd_fm801 4 , 351.Xr snd_gusc 4 , 352.Xr snd_hda 4 , 353.Xr snd_ich 4 , 354.Xr snd_maestro 4 , 355.Xr snd_maestro3 4 , 356.Xr snd_mss 4 , 357.Xr snd_neomagic 4 , 358.Xr snd_sbc 4 , 359.Xr snd_solo 4 , 360.Xr snd_spicds 4 , 361.Xr snd_t4dwave 4 , 362.Xr snd_uaudio 4 , 363.Xr snd_via8233 4 , 364.Xr snd_via82c686 4 , 365.Xr snd_vibes 4 , 366.Xr devfs 5 , 367.Xr loader.conf 5 , 368.Xr dmesg 8 , 369.Xr kldload 8 , 370.Xr sysctl 8 371.Rs 372.%T "The OSS API" 373.%O "http://www.opensound.com/pguide/oss.pdf" 374.Re 375.Sh HISTORY 376The 377.Nm 378device driver first appeared in 379.Fx 2.2.6 380as 381.Nm pcm , 382written by 383.An Luigi Rizzo . 384It was later 385rewritten in 386.Fx 4.0 387by 388.An Cameron Grant . 389The API evolved from the VOXWARE 390standard which later became OSS standard. 391.Sh AUTHORS 392.An -nosplit 393.An Luigi Rizzo Aq luigi@iet.unipi.it 394initially wrote the 395.Nm pcm 396device driver and this manual page. 397.An Cameron Grant Aq gandalf@vilnya.demon.co.uk 398later revised the device driver for 399.Fx 4.0 . 400.An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp 401revised this manual page. 402It was then rewritten for 403.Fx 5.2 . 404.Sh BUGS 405Some features of your sound card (e.g., global volume control) might not 406be supported on all devices. 407