share/man/man4/pcm.4

   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.12.2.11 2002/12/12 19:53:32 trhodes Exp $
  27 .\" $DragonFly: src/share/man/man4/pcm.4,v 1.3 2003/09/07 17:04:00 hmp Exp $
  28 .\"
  29 .Dd June 3, 1998
  30 .Dt PCM 4
  31 .Os
  32 .Sh NAME
  33 .Nm pcm ,
  34 .Nm snd
  35 .Nd FreeBSD PCM audio device driver
  36 .Sh SYNOPSIS
  37 For a card with bridge driver support, and a PnP card:
  38 .Cd "device pcm"
  39 .Pp
  40 For a card without bridge driver support, and a non-PnP card:
  41 .Cd "device pcm0 at isa? port? irq 5 drq 1 flags 0x15"
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 driver provides support for PCM audio play and capture.
  46 This driver
  47 also supports various PCI and WSS/MSS compatible ISA sound cards, and
  48 AC97 mixer.
  49 True full duplex operation is available on most cards.
  50 .Pp
  51 If your sound card is supported by a bridge driver,
  52 .Nm
  53 driver works
  54 in conjunction with the bridge driver.
  55 .Pp
  56 Apart from the usual parameters, the flags field is used to specify
  57 the secondary DMA channel (generally used for capture in full duplex
  58 cards). Flags are set to 0 for cards not using a secondary DMA
  59 channel, or to 0x10 + C to specify channel C.
  60 .Pp
  61 The driver works best with WSS/MSS cards, which have a very clean
  62 architecture and an orthogonal set of features.
  63 They also happen to be
  64 among the cheapest audio cards on the market.
  65 .Pp
  66 The driver does its best to recognize the installed hardware and drive
  67 it correctly, so that you don't have to give too many details in the
  68 kernel config files.
  69 For PCI and ISA PnP cards this is actually easy
  70 since they identify themselves.
  71 For legacy ISA cards, the driver looks
  72 for MSS cards at addresses 0x530 and 0x604 (obviously, unless overridden
  73 in the kernel config file by specifying an address).
  74 .Sh IOCTL
  75 The driver supports most of the Voxware ioctls(), and most
  76 applications work unmodified (including popular mpeg players and linux
  77 binaries). A few
  78 differences exist (the most important one is the ability to use
  79 memory-mapped access to the audio buffers). As a consequence, some
  80 applications may need to be recompiled with a slightly modified
  81 audio module.
  82 See
  83 .Aq Pa sys/soundcard.h
  84 for a complete list of the supported ioctls.
  85 .Sh SUPPORTED CARDS
  86 Below we include a list of supported codecs/cards.
  87 If your sound card
  88 is not listed here, it may be supported by a bridge driver.
  89 .Bl -tag -width 2m
  90 .It CS4237, CS4236, CS4232, CS4231 (ISA)
  91 All these cards work perfectly in full duplex using the MSS mode.
  92 This chipset is used, among others, on the A/Open AW35 and AW32, on
  93 some Intel motherboards, and (the CS4231) on some non-PnP cards.
  94 .Pp
  95 The CS4232 is reported as buggy in the Voxware documentation but
  96 I am not sure if this is true.
  97 On one of my Intel motherboards,
  98 capture does not work simply because the capture DMA channel is
  99 not wired to the ISA DMA controller.
 100 .It Yamaha OPL-SAx (ISA)
 101 Works perfectly in all modes.
 102 This chip is used in several PnP cards,
 103 but also (in non-PnP mode) on motherboards and laptops (e.g. the
 104 Toshiba Libretto).
 105 .It OPTi931 (ISA)
 106 The chip is buggy, but the driver has many workarounds to make it work
 107 in full duplex because for some time these were the only full duplex
 108 cards I could find. u-law formats uses U8 format internally because of
 109 a bug in the chip.
 110 .It Trident 4DWave DX/NX (PCI)
 111 .It ENSONIQ AudioPCI ES1370/1371 (PCI)
 112 Creative Labs SoundBlaster PCI is supported as well.
 113 .It ESS Solo-1/1E (PCI)
 114 .It NeoMagic 256AV/ZX (PCI)
 115 .El
 116 .Sh FILES
 117 The following commonly used symbolic links to real device nodes
 118 should be present:
 119 .Pp
 120 .Bl -tag -width /dev/sequencer -compact
 121 .It Pa /dev/audio
 122 Sparc-compatible audio device
 123 .It Pa /dev/dsp
 124 Digitized voice device
 125 .It Pa /dev/dspW
 126 Like
 127 .Pa /dev/dsp ,
 128 but 16 bits per sample
 129 .It Pa /dev/midi
 130 Raw midi access device
 131 .It Pa /dev/mixer
 132 Control port mixer device
 133 .It Pa /dev/music
 134 Level 2 sequencer interface
 135 .It Pa /dev/sequencer
 136 Sequencer device
 137 .It Pa /dev/pss
 138 Programmable device interface
 139 .El
 140 .Pp
 141 Each symbolic link refers to a device node of the same name,
 142 but with a unit number appended.
 143 The unit number for each device matches the unit number of the
 144 device probed at boot time.
 145 Device probe messages can be examined with the
 146 .Xr dmesg 8
 147 utility.
 148 .Pp
 149 All the appropriate device nodes and symbolic links
 150 for the
 151 .Ql pcm0
 152 device can be created with the following commands:
 153 .Bd -literal -offset indent
 154 cd /dev; sh MAKEDEV snd0
 155 .Ed
 156 .Pp
 157 Similarly, the device nodes and symbolic links for the
 158 .Ql pcm1
 159 device would be created as follows:
 160 .Bd -literal -offset indent
 161 cd /dev; sh MAKEDEV snd1
 162 .Ed
 163 .Pp
 164 Since the
 165 .Pa /dev/MAKEDEV
 166 utility creates symbolic links that will be used by
 167 many utilities by default,
 168 the device nodes and symbolic links for the
 169 preferred audio device in systems with multiple audio devices
 170 should be created last.
 171 .Sh DIAGNOSTICS AND TROUBLESHOOTING
 172 .Bl -tag -width 2m
 173 .It ac97: dac not ready
 174 AC97 codec is not likely to be accompanied with the sound card.
 175 .It unsupported subdevice XX
 176 A device node is not created properly.
 177 .El
 178 .Sh BUGS
 179 Some features of your cards (e.g. global volume control) might not
 180 be supported on all devices.
 181 .Sh HISTORY
 182 The
 183 .Nm
 184 device driver first appeared in
 185 .Fx 2.2.6 ,
 186 rewritten in
 187 .Fx 4.0 .
 188 .Sh SEE ALSO
 189 .Xr csa 4 ,
 190 .Xr gusc 4 ,
 191 .Xr sbc 4
 192 .Sh AUTHORS
 193 .An Luigi Rizzo Aq luigi@iet.unipi.it
 194 initially wrote the
 195 .Nm
 196 device driver and this manual page.
 197 .An Cameron Grant Aq gandalf@vilnya.demon.co.uk
 198 totally revised the device driver.
 199 .An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
 200 revised this manual page.