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