.\"
.\" Copyright (c) 1998, Luigi Rizzo
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/share/man/man4/pcm.4,v 1.12.2.11 2002/12/12 19:53:32 trhodes Exp $
.\" $DragonFly: src/share/man/man4/pcm.4,v 1.3 2003/09/07 17:04:00 hmp Exp $
.\"
.Dd June 3, 1998
.Dt PCM 4
.Os
.Sh NAME
.Nm pcm ,
.Nm snd
.Nd FreeBSD PCM audio device driver
.Sh SYNOPSIS
For a card with bridge driver support, and a PnP card:
.Cd "device pcm"
.Pp
For a card without bridge driver support, and a non-PnP card:
.Cd "device pcm0 at isa? port? irq 5 drq 1 flags 0x15"
.Sh DESCRIPTION
The
.Nm
driver provides support for PCM audio play and capture.
This driver
also supports various PCI and WSS/MSS compatible ISA sound cards, and
AC97 mixer.
True full duplex operation is available on most cards.
.Pp
If your sound card is supported by a bridge driver,
.Nm
driver works
in conjunction with the bridge driver.
.Pp
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.
.Pp
The driver works best with WSS/MSS cards, which have a very clean
architecture and an orthogonal set of features.
They also happen to be
among the cheapest audio cards on the market.
.Pp
The driver does its best to recognize the installed hardware and drive
it correctly, so that you don't have to give too many details in the
kernel config files.
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 (obviously, unless overridden
in the kernel config file by specifying an address).
.Sh IOCTL
The driver supports most of the Voxware ioctls(), and most
applications work unmodified (including popular mpeg players and linux
binaries). A few
differences exist (the most important one is the ability to use
memory-mapped access to the audio buffers). As a consequence, some
applications may need to be recompiled with a slightly modified
audio module.
See
.Aq Pa sys/soundcard.h
for a complete list of the supported ioctls.
.Sh 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.
.Bl -tag -width 2m
.It 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 Intel motherboards, and (the CS4231) on some non-PnP cards.
.Pp
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.
.It 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).
.It 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.
.It Trident 4DWave DX/NX (PCI)
.It ENSONIQ AudioPCI ES1370/1371 (PCI)
Creative Labs SoundBlaster PCI is supported as well.
.It ESS Solo-1/1E (PCI)
.It NeoMagic 256AV/ZX (PCI)
.El
.Sh FILES
The following commonly used symbolic links to real device nodes
should be present:
.Pp
.Bl -tag -width /dev/sequencer -compact
.It Pa /dev/audio
Sparc-compatible audio device
.It Pa /dev/dsp
Digitized voice device
.It Pa /dev/dspW
Like
.Pa /dev/dsp ,
but 16 bits per sample
.It Pa /dev/midi
Raw midi access device
.It Pa /dev/mixer
Control port mixer device
.It Pa /dev/music
Level 2 sequencer interface
.It Pa /dev/sequencer
Sequencer device
.It Pa /dev/pss
Programmable device interface
.El
.Pp
Each symbolic link refers to a device node of the same name,
but with a unit number appended.
The unit number for each device matches the unit number of the
device probed at boot time.
Device probe messages can be examined with the
.Xr dmesg 8
utility.
.Pp
All the appropriate device nodes and symbolic links
for the
.Ql pcm0
device can be created with the following commands:
.Bd -literal -offset indent
cd /dev; sh MAKEDEV snd0
.Ed
.Pp
Similarly, the device nodes and symbolic links for the
.Ql pcm1
device would be created as follows:
.Bd -literal -offset indent
cd /dev; sh MAKEDEV snd1
.Ed
.Pp
Since the
.Pa /dev/MAKEDEV
utility creates symbolic links that will be used by
many utilities by default,
the device nodes and symbolic links for the
preferred audio device in systems with multiple audio devices
should be created last.
.Sh DIAGNOSTICS AND TROUBLESHOOTING
.Bl -tag -width 2m
.It ac97: dac not ready
AC97 codec is not likely to be accompanied with the sound card.
.It unsupported subdevice XX
A device node is not created properly.
.El
.Sh BUGS
Some features of your cards (e.g. global volume control) might not
be supported on all devices.
.Sh HISTORY
The
.Nm
device driver first appeared in
.Fx 2.2.6 ,
rewritten in
.Fx 4.0 .
.Sh SEE ALSO
.Xr csa 4 ,
.Xr gusc 4 ,
.Xr sbc 4
.Sh AUTHORS
.An Luigi Rizzo Aq luigi@iet.unipi.it
initially wrote the
.Nm
device driver and this manual page.
.An Cameron Grant Aq gandalf@vilnya.demon.co.uk
totally revised the device driver.
.An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
revised this manual page.