home | help
PCM(4)			     Kernel Interfaces Manual			  PCM(4)

NAME
     pcm, snd -- FreeBSD PCM audio device infrastructure

SYNOPSIS
     For a card with bridge driver support, and a PnP card:
     device pcm

     For a card without bridge driver support, and a non-PnP card, the following
     lines may be required in /boot/device.hints:
     hint.pcm.0.at="isa"
     hint.pcm.0.irq="5"
     hint.pcm.0.drq="1"
     hint.pcm.0.flags="0x0"

DESCRIPTION
     The  pcm driver provides support for PCM audio play and capture.  This dri-
     ver also supports various PCI, WSS/MSS compatible,  ISA  sound  cards,  and
     AC97  mixer.  Once the pcm 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 opera-
     tion is available on most cards.

     If  the sound card is supported by a bridge driver, the pcm 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 works best with WSS/MSS cards, which have a very clean architec-
     ture  and	an orthogonal set of features.	They also happen to be among the
     cheapest audio cards on the market.

     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 foo and can be loaded
     by the boot loader via boot/loader.conf 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.

   VCHANS
     Each  device  can	optionally  support more playback channels that 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
     The following sysctl(8) tunables are available:

	   hw.snd.pcm%d.buffersize     Configure the amount of	DMA  bufferspace
				       available for a device.

	   hw.snd.targetirqrate        Set the default block size such that con-
				       tinuous	playback  will	achieve this IRQ
				       rate.  This value can be tuned to improve
				       application performance.   Increase  this
				       value when the sound lags and decrease it
				       if sound stutters or breaks up.

	   hw.snd.unit		       When  using  devfs(5), the default device
				       for /dev/dsp.  Equivalent  to  a  symlink
				       from /dev/dsp to /dev/dsp${hw.snd.unit}.

	   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 na-
				       tively supports.

	   hw.snd.verbose	       Level of verbosity for  the  /dev/sndstat
				       device.	 Higher values include more out-
				       put and the highest level, three,  should
				       be  used  when  reported 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 sound
				       loaded modules.

	   hw.snd.maxautovchans        Global VCHAN setting  that  only  affects
				       devices that have only one playback chan-
				       nel.   The  sound system will dynamically
				       create up this many VCHANs.  Set  to  "0"
				       if no VCHANS are desired.

	   hw.snd.pcm%d.vchans	       The  current  number  of VCHANs allocated
				       per device.  This can be set to	preallo-
				       cate a certain number of VCHANs.  Setting
				       this value to "0" will disable VCHANs for
				       this device.

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

   Statistics
     Channel statistics are only kept while the device is open.  So with  situa-
     tions  involving  overruns and underruns, consider the output while the er-
     rant application is open and running.

   IOCTL Support
     The driver supports most of the OSS ioctl() functions,  and  most	applica-
     tions  work unmodified.  A few differences exist, while memory mapped play-
     back 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
     <sys/soundcard.h> for a complete list of the supported ioctl() functions.

   SUPPORTED CARDS
     Below  we	include a list of supported codecs/cards.  If your sound card is
     not listed here, it may be supported by a bridge driver.

     CS4237, CS4236, CS4232, CS4231 (ISA)
	 All these cards work perfectly in full duplex using the MSS mode.  This
	 chipset is used, among others, on the A/Open AW35 and AW32, on some In-
	 tel motherboards, and (the CS4231) on some non-PnP cards.

	 The CS4232 is reported as buggy in the Voxware documentation but  I  am
	 not  sure  if	this  is true.	On one of my Intel motherboards, capture
	 does not work simply because the capture DMA channel is  not  wired  to
	 the ISA DMA controller.

     Yamaha OPL-SAx (ISA)
	 Works	perfectly in all modes.  This chip is used in several PnP cards,
	 but also (in non-PnP  mode)  on  motherboards	and  laptops  (e.g.  the
	 Toshiba Libretto).

     OPTi931 (ISA)
	 The  chip is buggy, but the driver has many workarounds to make it work
	 in full duplex because for some time these were the  only  full  duplex
	 cards	I could find. u-law formats uses U8 format internally because of
	 a bug in the chip.

     Trident 4DWave DX/NX (PCI)

     ENSONIQ AudioPCI ES1370/1371 (PCI)
	 Creative Labs SoundBlaster PCI is supported as well.

     ESS Solo-1/1E (PCI)

     NeoMagic 256AV/ZX (PCI)

FILES
     The pcm 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/dspr%d.%d	Should be connected to a record codec.
     /dev/sndstat	Current pcm status, including all channels and drivers.

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

DIAGNOSTICS
     ac97: dac not ready
	 AC97 codec is not likely to be accompanied with the sound card.

     unsupported subdevice XX
	 A device node is not created properly.

BUGS
     Some  features of your cards (e.g. global volume control) might not be sup-
     ported on all devices.

HISTORY
     The pcm device driver first appeared in  FreeBSD  2.2.6  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.

SEE ALSO
     csa(4), gusc(4), sbc(4), devfs(5),  loader.conf(5),  dmesg(8),  kldload(8),
     sysctl(8)

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

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.

FreeBSD 5.2.1			November 14, 2003			  PCM(4)

home | help