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