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$
  27 .\"
  28 .Dd June 3, 1998
  29 .Dt PCM 4
  30 .Os FreeBSD
  31 .Sh NAME
  32 .Nm pcm
  33 .Nd FreeBSD audio device driver
  34 .Sh SYNOPSIS
  35 .Cd "device pcm0 at isa? port? irq 5 drq 1 flags 0x15"
  36 .Sh DESCRIPTION
  37 The
  38 .Nm pcm
  39 driver provides support for various ISA sound cards that are compatible
  40 with the WSS/MSS specs, or with the SBPro and SB16. Only audio
  41 capture/playback is supported by the driver, and true full duplex
  42 operation is available on most cards.
  43 .Pp
  44 Apart from the usual parameters, the flags field is used to specify
  45 the secondary DMA channel (generally used for capture in full duplex
  46 cards). Flags are set to 0 for cards not using a secondary DMA
  47 channel, or to 0x10 + C to specify channel C.
  48 .Pp
  49 PnP audio cards are also supported using the
  50 .Nm pnp
  51 support which is available in
  52 .Fx
  53 starting from release 2.2.6.
  54 See the
  55 .Xr pnp 4
  56 manpage for more information. In particular, remember that unit
  57 numbers for (recognized)
  58 PnP cards are assigned after the legacy ISA devices, and that the
  59 actual resources (port, irq and drq) used by the driver are read from
  60 the PnP configuration and not from the "device pcm0" line.
  61 So, if you have the following line in your kernel config file:
  62 .Pp
  63 .Cd "device pcm0 ..."
  64 .Pp
  65 your first PnP audio card will be unit #1, i.e. it will be accessible as
  66 .Pa /dev/audio1 ,
  67 .Pa /dev/dsp1 ,
  68 etc.
  69 Many applications default to using /dev/audio, but appropriate
  70 symlinks will be created as a side-effect of the the following command:
  71 .Pp
  72 .Cd cd /dev
  73 .Cd ./MAKEDEV snd1
  74 .Pp
  75 The driver works best with WSS/MSS cards, which have a very clean
  76 architecture and an orthogonal set of features. They also happen to be
  77 among the cheapest audio cards on the market.
  78 Other cards such as SB and ESS have a more complex internal
  79 architecture, and often no documentation available. As a consequence,
  80 support for these cards is slightly worse.
  81 .Pp
  82 The driver does its best to recognize the installed harware and drive
  83 it correctly, so that you don't have to give too many details in the
  84 kernel config files. For PnP cards this is actually easy since they
  85 identify themselves. For legacy ISA cards, the driver first looks for
  86 MSS cards at addresses 0x530 and 0x604, then for SB
  87 cards at 0x220 and 0x240 (obviously, unless overridden in the kernel
  88 config file by specifying an address).
  89
  90 .Sh IOCTL
  91 The driver supports most of the Voxware ioctls(), and most
  92 applications work unmodified (including popular mpeg players and linux
  93 binaries). A few
  94 differences exist (the most important one is the ability to use
  95 memory-mapped access to the audio buffers). As a consequence, some
  96 applications may need to be recompiled with a slightly modified
  97 audio module.  See /usr/include/machine/soundcard.h for a complete
  98 list of the supported ioctls.
  99
 100 .Sh SUPPORTED CARDS
 101 .Pp
 102 Below we include a list of supported codecs/cards, including, if
 103 possible, the pnp configuration information where applicable
 104 (we give default parameters, your actual resources may vary).
 105
 106 .Bl -tag -width 2m  % begin list
 107 .It CS4237, CS4236, CS4232, CS4231
 108 .Cd "pnp 1 0 os enable port0 0x534 port2 0x220 irq0 5 drq0 1 drq1 3"
 109 .Pp
 110 All these cards work perfectly in full duplex using the MSS mode.
 111 This chipset is used, among others, on the A/Open AW35 and AW32, on
 112 some Intel motherboards, and (the CS4231) on some non-PnP cards.
 113 .Pp
 114 The CS4232 is reported as buggy in the Voxware documentation but
 115 I am not sure if this is true. On one of my Intel motherboards,
 116 capture does not work simply because the capture DMA channel is
 117 not wired to the ISA DMA controller.
 118
 119 .It GUSPnP
 120 .Cd "pnp 1 0 os enable port0 0x220 port1 0x320 port2 0x32c irq0 5 drq0 7 drq1 5"
 121 .Pp
 122 Supported in full duplex using the MSS mode. The GUSPnP does not use a
 123 real CS4231, and I suspect a bug in the emulation when operating
 124 with mu-law format. Since the card is discontinued, I did not bother
 125 to include special code to set the card in "Mode3" (where mu-law is
 126 known to work) and rather I use U8 format internally, and do the
 127 conversion in software within the driver. This loses resolution,
 128 so you should use 16-bit modes with this card when possible.
 129
 130 .It Yamaha OPL-SAx
 131 .Cd "pnp 1 0 os enable port0 0x220 port1 0x530 port2 0x388 port3 0x370 irq0 5 drq0 1 drq1 3"
 132 .Pp
 133 Works perfectly in all modes. This chip is used in several PnP cards,
 134 but also (in non-PnP mode) on motherboards and laptops (e.g. the
 135 Toshiba Libretto).
 136
 137 .It OPTi931
 138 .Cd "pnp 1 1 os enable port0 0x534 port2 0x220 port3 0xe0d irq0 10 drq0 1 drq1 6"
 139 .Pp
 140 The chip is buggy, but the driver has many workarounds to make it work
 141 in full duplex because for some time these were the only full duplex
 142 cards I could find. u-law formats uses U8 format internally because of
 143 a bug in the chip.
 144
 145 .It SB16, Vibra16C, and old SB16/AWExx cards
 146 .Cd "pnp 1 0 os enable port0 0x220 irq0 5 drq0 1 drq1 5"
 147 .Pp
 148 These codecs have limited full duplex capabilities, by doing 8-bit
 149 in one direction and 16-bit in the other one. The driver supports this
 150 mode of operation but keep in mind that it is not a supported mode of
 151 operation from CreativeLabs.
 152
 153 .It Vibra16X and newer SB16/AWExx cards
 154 .Cd "pnp 1 0 os enable port0 0x220 irq0 5 drq0 1 drq1 3"
 155 .Pp
 156 Recently CreativeLabs has changed the codec (DSP) and the new one is
 157 somewhat different from the old one. The most apparent difference is
 158 the use of two 8-bit DMA channels, which seems to have broken our full
 159 duplex support. Maybe one can achieve full duplex by making use of the
 160 wavetable to play audio, but since this driver does not support the
 161 wavetable you have to stick with half duplex.
 162
 163 .It SBPro and clones
 164 This is the default mode of operation for most other cards. We have
 165 only limited (and possibly buggy) support for them: 8-bit, half
 166 duplex, even if the hardware in some cases (e.g. ESS chips) might do more.
 167 .El
 168 .Pp
 169 .Sh DIAGNOSTICS AND TROUBLESHOOTING
 170 .Bl -tag -width 2m
 171 .It "This is XXX but LDN Y is disabled"
 172 .Pp
 173 This means that the bios has left the PnP device disabled, and you
 174 have to enable it manually booting with "-c" and giving the pnp
 175 configuration shown above.
 176 .It "pcmX: unit not configured, perhaps you want pcmY ?"
 177 This means that you are using the wrong unit. Generally this happens
 178 when you are using a PnP card without creating the symlinks to the
 179 correct unit.  Re-create the symlinks (and possibly also the device
 180 entries) in the /dev directory to point to the right one.
 181
 182 .It "timeout flushing dbuf_out ..."
 183 This means a problem in the configuration of the card (specifically,
 184 in the DMA channel) or (much less likely) in the driver, which has
 185 not recognized the card correctly. Check the DMA channel used for
 186 capture.
 187
 188 .It capture does not work
 189 This usually happens when the input dma channel is misconfigured.
 190
 191 .El
 192 .Sh BUGS
 193 Due to lack of documentation,
 194 SB16 support is not very good. Also, mixer support is not complete,
 195 and some features of your cards (e.g. global volume control) might not
 196 be supported on all devices.
 197 .Sh HISTORY
 198 The
 199 .Nm pcm
 200 device driver first appeared in
 201 .Fx 2.2.6
 202 .Sh AUTHORS
 203 The
 204 .Nm
 205 device driver and this manual page were written by
 206 .An Luigi Rizzo Aq luigi@iet.unipi.it