Provided by: freebsd-manpages_7.2-1_all bug

NAME

     sound, pcm, snd - FreeBSD PCM audio device infrastructure

SYNOPSIS

     To compile this driver into the kernel, place the following line in your
     kernel configuration file:

           device sound

     Non-PnP sound cards require the following lines in device.hints(5):

           hint.pcm.0.at="isa"
           hint.pcm.0.irq="5"
           hint.pcm.0.drq="1"
           hint.pcm.0.flags="0x0"

DESCRIPTION

     Note: There exists some ambiguity in the naming at the moment (sound,
     pcm, snd).  It will be resolved soon by renaming device sound to device
     snd, and doing associated changes.

     The sound driver provides support for PCM audio play and capture.  This
     driver also supports various PCI, ISA, WSS/MSS compatible sound cards,
     AC97 mixer and High Definition Audio.  Once the sound driver attaches,
     supported devices provide audio record and playback channels.  The
     FreeBSD sound system provides dynamic mixing “VCHAN” and rate conversion
     “soft formats”.  True full duplex operation is available on most sound
     cards.

     If the sound card is supported by a bridge driver, the sound driver works
     in conjunction with the bridge driver.

     Apart from the usual parameters, the flags field is used to specify the
     secondary DMA channel (generally used for capture in full duplex cards).
     Flags are set to 0 for cards not using a secondary DMA channel, or to
     0x10 + C to specify channel C.

     The driver does its best to recognize the installed hardware and drive it
     correctly so the user is not required to add several lines in
     /boot/device.hints.  For PCI and ISA PnP cards this is actually easy
     since they identify themselves.  For legacy ISA cards, the driver looks
     for MSS cards at addresses 0x530 and 0x604 (unless overridden in
     /boot/device.hints).

   Boot Variables
     In general, the module snd_foo corresponds to device snd_foo and can be
     loaded by the boot loader(8) via loader.conf(5) or from the command line
     using the kldload(8) utility.  Options which can be specified in
     /boot/loader.conf include:

           snd_driver_load   (“NO”) If set to “YES”, this option loads all
                             available drivers.

           snd_emu10k1_load  (“NO”) If set to “YES”, only the SoundBlaster 5.1
                             driver and dependent modules will be loaded.

           snd_foo_load      (“NO”) If set to “YES”, load driver for
                             card/chipset foo.

     To define default values for the different mixer channels, set the
     channel to the preferred value using hints, e.g.: hint.pcm.0.line="0".
     This will mute the input channel per default.

   VCHANs
     Each device can optionally support more playback and recording channels
     than physical hardware provides by using “virtual channels” or VCHANs.
     VCHAN options can be configured via the sysctl(8) interface but can only
     be manipulated while the device is inactive.

   Runtime Configuration
     There are a number of sysctl(8) variables available.  hw.snd.* tunables
     are global settings and dev.pcm.* are device specific.

           hw.snd.latency_profile      Define sets of buffering latency
                                       conversion tables for the
                                       hw.snd.latency tunable.  A value of 0
                                       will use a low and aggressive latency
                                       profile which can result in possible
                                       underruns if the application cannot
                                       keep up with a rapid irq rate,
                                       especially during high workload.  The
                                       default value is 1, which is considered
                                       a moderate/safe latency profile.

           hw.snd.latency              Configure the buffering latency.  Only
                                       affects applications that do not
                                       explicitly request blocksize /
                                       fragments.  This tunable provides finer
                                       granularity than the
                                       hw.snd.latency_profile tunable.
                                       Possible values range between 0 (lowest
                                       latency) and 10 (highest latency).

           hw.snd.report_soft_formats  Controls the internal format conversion
                                       if it is available transparently to the
                                       application software.  When disabled or
                                       not available, the application will
                                       only be able to select formats the
                                       device natively supports.

           hw.snd.compat_linux_mmap    Enable to allow PROT_EXEC page
                                       mappings.  All Linux applications using
                                       sound and mmap(2) require this.

           hw.snd.feeder_rate_round    Sample rate rounding threshold, to
                                       avoid large prime division at the cost
                                       of accuracy.  All requested sample
                                       rates will be rounded to the nearest
                                       threshold value.  Possible values range
                                       between 0 (disabled) and 500.  Default
                                       is 25.

           hw.snd.feeder_rate_max      Maximum allowable sample rate.

           hw.snd.feeder_rate_min      Minimum allowable sample rate.

           hw.snd.verbose              Level of verbosity for the /dev/sndstat
                                       device.  Higher values include more
                                       output and the highest level, four,
                                       should be used when reporting problems.
                                       Other options include:

                                       0   Installed devices and their
                                           allocated bus resources.

                                       1   The number of playback, record,
                                           virtual channels, and flags per
                                           device.

                                       2   Channel information per device
                                           including the channel’s current
                                           format, speed, and pseudo device
                                           statistics such as buffer overruns
                                           and buffer underruns.

                                       3   File names and versions of the
                                           currently loaded sound modules.

                                       4   Various messages intended for
                                           debugging.

           hw.snd.maxautovchans        Global VCHAN setting that only affects
                                       devices with at least one playback or
                                       recording channel available.  The sound
                                       system will dynamically create up this
                                       many VCHANs.  Set to “0” if no VCHANS
                                       are desired.  Maximum value is 256.

           hw.snd.default_unit         Default sound card for systems with
                                       multiple sound cards.  When using
                                       devfs(5), the default device for
                                       /dev/dsp.  Equivalent to a symlink from
                                       /dev/dsp to
                                       /dev/dsp${hw.snd.default_unit}.

           hw.snd.default_auto         Enable to automatically assign default
                                       sound unit to the most recent attached
                                       device.

           dev.pcm.%d.[play|rec].vchans
                                       The current number of VCHANs allocated
                                       per device.  This can be set to
                                       preallocate a certain number of VCHANs.
                                       Setting this value to “0” will disable
                                       VCHANs for this device.

           dev.pcm.%d.[play|rec].vchanrate
                                       Sample rate speed for VCHAN mixing.
                                       All playback paths will be converted to
                                       this sample rate before the mixing
                                       process begins.

           dev.pcm.%d.[play|rec].vchanformat
                                       Format for VCHAN mixing.  All playback
                                       paths will be converted to this format
                                       before the mixing process begins.

           dev.pcm.%d.polling          Experimental polling mode support where
                                       the driver operates by querying the
                                       device state on each tick using a
                                       callout(9) mechanism.  Disabled by
                                       default and currently only available
                                       for a few device drivers.

   Recording Channels
     On devices that have more than one recording source (ie: mic and line),
     there is a corresponding /dev/dsp%d.r%d device.

   Statistics
     Channel statistics are only kept while the device is open.  So with
     situations involving overruns and underruns, consider the output while
     the errant application is open and running.

   IOCTL Support
     The driver supports most of the OSS ioctl() functions, and most
     applications work unmodified.  A few differences exist, while memory
     mapped playback is supported natively and in Linux emulation, memory
     mapped recording is not due to VM system design.  As a consequence, some
     applications may need to be recompiled with a slightly modified audio
     module.  See #include <sys/soundcard.h>
     for a complete list of the supported ioctl() functions.

FILES

     The sound drivers may create the following device nodes:

     /dev/audio%d.%d  Sparc-compatible audio device.
     /dev/dsp%d.%d    Digitized voice device.
     /dev/dspW%d.%d   Like /dev/dsp, but 16 bits per sample.
     /dev/dsp%d.p%d   Playback channel.
     /dev/dsp%d.r%d   Record channel.
     /dev/dsp%d.vp%d  Virtual playback channel.
     /dev/dsp%d.vr%d  Virtual recording channel.
     /dev/sndstat     Current sound status, including all channels and
                      drivers.

     The first number in the device node represents the unit number of the
     sound device.  All sound devices are listed in /dev/sndstat.  Additional
     messages are sometimes recorded when the device is probed and attached,
     these messages can be viewed with the dmesg(8) utility.

     The above device nodes are only created on demand through the dynamic
     devfs(5) clone handler.  Users are strongly discouraged to access them
     directly.  For specific sound card access, please instead use /dev/dsp or
     /dev/dsp%d.

DIAGNOSTICS

     pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead  The
     hardware does not generate interrupts to serve incoming (play) or
     outgoing (record) data.

     unsupported subdevice XX  A device node is not created properly.

SEE ALSO

     snd_ad1816(4), snd_als4000(4), snd_atiixp(4), snd_audiocs(4), snd_cmi(4),
     snd_cs4281(4), snd_csa(4), snd_ds1(4), snd_emu10k1(4), snd_emu10kx(4),
     snd_envy24(4), snd_envy24ht(4), snd_es137x(4), snd_ess(4), snd_fm801(4),
     snd_gusc(4), snd_hda(4), snd_ich(4), snd_maestro(4), snd_maestro3(4),
     snd_mss(4), snd_neomagic(4), snd_sbc(4), snd_solo(4), snd_spicds(4),
     snd_t4dwave(4), snd_uaudio(4), snd_via8233(4), snd_via82c686(4),
     snd_vibes(4), devfs(5), device.hints(5), loader.conf(5), dmesg(8),
     kldload(8), sysctl(8)

     The OSS API, http://www.opensound.com/pguide/oss.pdf.

HISTORY

     The sound device driver first appeared in FreeBSD 2.2.6 as pcm, written
     by Luigi Rizzo.  It was later rewritten in FreeBSD 4.0 by Cameron Grant.
     The API evolved from the VOXWARE standard which later became OSS
     standard.

AUTHORS

     Luigi Rizzo 〈luigi@iet.unipi.it〉 initially wrote the pcm device driver
     and this manual page.  Cameron Grant 〈gandalf@vilnya.demon.co.uk〉 later
     revised the device driver for FreeBSD 4.0.  Seigo Tanimura
     〈tanimura@r.dl.itc.u-tokyo.ac.jp〉 revised this manual page.  It was then
     rewritten for FreeBSD 5.2.

BUGS

     Some features of your sound card (e.g., global volume control) might not
     be supported on all devices.