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.\"
| 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.\"
|
29.Dt PCM 4
30.Os
31.Sh NAME
32.Nm pcm ,
33.Nm snd
34.Nd
35.Fx
36PCM audio device infrastructure
37.Sh SYNOPSIS
38For a card with bridge driver support, and a PnP card:
39.Cd "device pcm"
40.Pp
41For a card without bridge driver support, and a non-PnP card,
42the following lines may be required in
43.Pa /boot/device.hints :
44.Cd hint.pcm.0.at="isa"
45.Cd hint.pcm.0.irq="5"
46.Cd hint.pcm.0.drq="1"
47.Cd hint.pcm.0.flags="0x0"
48.Sh DESCRIPTION
49The
50.Nm
51driver provides support for
52.Tn PCM
53audio play and capture.
54This driver also supports various
55.Tn PCI ,
56.Tn WSS/MSS
57compatible,
58.Tn ISA
59sound cards, and AC97 mixer.
60Once the
61.Nm
62driver attaches, supported devices provide audio record and
63playback channels.
64The
65.Fx
66sound system provides dynamic mixing
67.Dq VCHAN
68and rate conversion
69.Dq soft formats .
70True full duplex operation is available on most cards.
71.Pp
72If the sound card is supported by a bridge driver, the
73.Nm
74driver works in conjunction with the bridge driver.
75.Pp
76Apart from the usual parameters, the flags field is used to specify
77the secondary
78.Tn DMA
79channel (generally used for capture in full duplex cards).
80Flags are set to 0 for cards not using a secondary
81.Tn DMA
82channel, or to 0x10 + C to specify channel C.
83.Pp
84The driver works best with
85.Tn WSS/MSS
86cards, which have a very clean
87architecture and an orthogonal set of features.
88They also happen to be
89among the cheapest audio cards on the market.
90.Pp
91The driver does its best to recognize the installed hardware and drive
92it correctly so the user is not required to add several lines in
93.Pa /boot/device.hints .
94For
95.Tn PCI
96and
97.Tn ISA
98.Tn PnP
99cards this is actually easy
100since they identify themselves.
101For legacy
102.Tn ISA
103cards, the driver looks for
104.Tn MSS
105cards at addresses 0x530 and 0x604 (unless overridden
106in
107.Pa /boot/device.hints ) .
108.Ss Boot Variables
109In general, the module
110.Pa snd_foo
111corresponds to
112.Cd "device foo"
113and can be
114loaded by the boot
115.Xr loader 8
116via
117.Xr loader.conf 5
118or from the command line using the
119.Xr kldload 8
120utility.
121Options which can be specified in
122.Pa /boot/loader.conf
123include:
124.Bl -tag -width ".Va snd_emu10k1_load" -offset indent
125.It Va snd_driver_load
126.Pq Dq Li NO
127If set to
128.Dq Li YES ,
129this option loads all available drivers.
130.It Va snd_emu10k1_load
131.Pq Dq Li NO
132If set to
133.Dq Li YES ,
134only the SoundBlaster 5.1 driver and dependent modules will be loaded.
135.It Va snd_foo_load
136.Pq Dq Li NO
137If set to
138.Dq Li YES ,
139load driver for card/chipset foo.
140.El
141.Pp
142To define default values for the different mixer channels,
143set the channel to the prefered value using hints, e.g.:
144.Va hint.pcm.0.line Ns = Ns Qq Li 0 .
145This will mute the input channel per default.
146.Ss VCHANs
147Each device can optionally support more playback channels
148that physical hardware provides by using
149.Dq virtual channels
150or
151.Tn VCHANs .
152.Tn VCHAN
153options can be configured via the
154.Xr sysctl 8
155interface but can only be manipulated while the device is inactive.
156.Ss Runtime Configuration
157The following
158.Xr sysctl 8
159variables are available:
160.Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent
161.It Va hw.snd.pcm%d.buffersize
162Configure the amount of
163.Tn DMA
164bufferspace available for a device.
165.It Va hw.snd.targetirqrate
166Set the default block size such that continuous
167playback will achieve this
168.Tn IRQ
169rate.
170This value can be tuned to improve application performance.
171Increase this value when the sound lags and decrease
172it if sound stutters or breaks up.
173.It Va hw.snd.unit
174When using
175.Xr devfs 5 ,
176the default device for
177.Pa /dev/dsp .
178Equivalent to a symlink from
179.Pa /dev/dsp
180to
181.Pa /dev/dsp Ns Va ${hw.snd.unit} .
182.It Va hw.snd.report_soft_formats
183Controls the internal format conversion if it is
184available transparently to the application software.
185When disabled or not available, the application will
186only be able to select formats the device natively supports.
187.It Va hw.snd.verbose
188Level of verbosity for the
189.Pa /dev/sndstat
190device.
191Higher values include more output and the highest level,
192three, should be used when reporting problems.
193Other options include:
194.Bl -tag -width 2n
195.It 0
196Installed devices and their allocated bus resources.
197.It 1
198The number of playback, record, virtual channels, and
199flags per device.
200.It 2
201Channel information per device including the channel's
202current format, speed, and pseudo device statistics such as
203buffer overruns and buffer underruns.
204.It 3
205File names and versions of the currently sound loaded modules.
206.El
207.It Va hw.snd.maxautovchans
208Global
209.Tn VCHAN
210setting that only affects devices that have only one playback channel.
211The sound system will dynamically create up this many
212.Tn VCHANs .
213Set to
214.Dq 0
215if no
216.Tn VCHANS
217are desired.
218.It Va hw.snd.pcm%d.vchans
219The current number of
220.Tn VCHANs
221allocated per device.
222This can be set to preallocate a certain number of
223.Tn VCHANs .
224Setting this value to
225.Dq 0
226will disable
227.Tn VCHANs
228for this device.
229.El
230.Ss Recording Channels
231On devices that have more than one recording source (ie: mic and line),
232there is a corresponding
233.Pa /dev/dspr%d.%d
234device.
235.Ss Statistics
236Channel statistics are only kept while the device is open.
237So with situations involving overruns and underruns, consider the output
238while the errant application is open and running.
239.Ss IOCTL Support
240The driver supports most of the
241.Tn OSS
242.Fn ioctl
243functions, and most applications work unmodified.
244A few differences exist, while memory mapped playback is
245supported natively and in
246.Tn Linux
247emulation, memory mapped recording is
248not due to
249.Tn VM
250system design.
251As a consequence, some applications may need to be recompiled
252with a slightly modified audio module.
253See
254.In sys/soundcard.h
255for a complete list of the supported
256.Fn ioctl
257functions.
258.Ss Supported Cards
259Below we include a list of supported codecs/cards.
260If your sound card
261is not listed here, it may be supported by a bridge driver.
262.Bl -tag -width 2m
263.It CS4237, CS4236, CS4232, CS4231 (ISA)
264All these cards work perfectly in full duplex using the MSS mode.
265This chipset is used, among others, on the A/Open AW35 and AW32, on
266some Intel motherboards, and (the CS4231) on some non-PnP cards.
267.Pp
268The CS4232 is reported as buggy in the Voxware documentation but
269I am not sure if this is true.
270On one of my Intel motherboards,
271capture does not work simply because the capture DMA channel is
272not wired to the ISA DMA controller.
273.It Yamaha OPL-SAx (ISA)
274Works perfectly in all modes.
275This chip is used in several PnP cards,
276but also (in non-PnP mode) on motherboards and laptops (e.g., the
277Toshiba Libretto).
278.It OPTi931 (ISA)
279The chip is buggy, but the driver has many workarounds to make it work
280in full duplex because for some time these were the only full duplex
281cards I could find.
282U-law format uses U8 format internally because of
283a bug in the chip.
284.It Trident 4DWave DX/NX (PCI)
285.It ENSONIQ AudioPCI ES1370/1371 (PCI)
286Creative Labs SoundBlaster PCI is supported as well.
287.It ESS Solo-1/1E (PCI)
288.It NeoMagic 256AV/ZX (PCI)
289.El
290.Sh FILES
291The
292.Nm
293drivers may create the following
294device nodes:
295.Pp
296.Bl -tag -width ".Pa /dev/audio%d.%d" -compact
297.It Pa /dev/audio%d.%d
298Sparc-compatible audio device.
299.It Pa /dev/dsp%d.%d
300Digitized voice device.
301.It Pa /dev/dspW%d.%d
302Like
303.Pa /dev/dsp ,
304but 16 bits per sample.
305.It Pa /dev/dspr%d.%d
306Should be connected to a record codec.
307.It Pa /dev/sndstat
308Current
309.Nm
310status, including all channels and drivers.
311.El
312.Pp
313The first number in the device node
314represents the unit number of the
315.Nm
316device.
317All
318.Nm
319devices are listed
320in
321.Pa /dev/sndstat .
322Additional messages are sometimes recorded when the
323device is probed and attached, these messages can be viewed with the
324.Xr dmesg 8
325utility.
326.Sh DIAGNOSTICS
327.Bl -diag
328.It ac97: dac not ready
329AC97 codec is not likely to be accompanied with the sound card.
330.It unsupported subdevice XX
331A device node is not created properly.
332.El
333.Sh BUGS
334Some features of your cards (e.g., global volume control) might not
335be supported on all devices.
336.Sh HISTORY
337The
338.Nm
339device driver first appeared in
340.Fx 2.2.6
341written by
342.An Luigi Rizzo .
343It was later
344rewritten in
345.Fx 4.0
346by
347.An Cameron Grant .
348The API evolved from the VOXWARE
349standard which later became OSS standard.
350.Sh SEE ALSO
351.Xr csa 4 ,
352.Xr gusc 4 ,
353.Xr sbc 4 ,
354.Xr devfs 5 ,
355.Xr loader.conf 5 ,
356.Xr dmesg 8 ,
357.Xr kldload 8 ,
358.Xr sysctl 8
359.Rs
360.%T "The OSS API"
361.%O "http://www.opensound.com/pguide/oss.pdf"
362.Re
363.Sh AUTHORS
364.An -nosplit
365.An Luigi Rizzo Aq luigi@iet.unipi.it
366initially wrote the
367.Nm
368device driver and this manual page.
369.An Cameron Grant Aq gandalf@vilnya.demon.co.uk
370later revised the device driver for
371.Fx 4.0 .
372.An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
373revised this manual page.
374It was then rewritten for
375.Fx 5.2 .
| 29.Dt PCM 4
30.Os
31.Sh NAME
32.Nm pcm ,
33.Nm snd
34.Nd
35.Fx
36PCM audio device infrastructure
37.Sh SYNOPSIS
38For a card with bridge driver support, and a PnP card:
39.Cd "device pcm"
40.Pp
41For a card without bridge driver support, and a non-PnP card,
42the following lines may be required in
43.Pa /boot/device.hints :
44.Cd hint.pcm.0.at="isa"
45.Cd hint.pcm.0.irq="5"
46.Cd hint.pcm.0.drq="1"
47.Cd hint.pcm.0.flags="0x0"
48.Sh DESCRIPTION
49The
50.Nm
51driver provides support for
52.Tn PCM
53audio play and capture.
54This driver also supports various
55.Tn PCI ,
56.Tn WSS/MSS
57compatible,
58.Tn ISA
59sound cards, and AC97 mixer.
60Once the
61.Nm
62driver attaches, supported devices provide audio record and
63playback channels.
64The
65.Fx
66sound system provides dynamic mixing
67.Dq VCHAN
68and rate conversion
69.Dq soft formats .
70True full duplex operation is available on most cards.
71.Pp
72If the sound card is supported by a bridge driver, the
73.Nm
74driver works in conjunction with the bridge driver.
75.Pp
76Apart from the usual parameters, the flags field is used to specify
77the secondary
78.Tn DMA
79channel (generally used for capture in full duplex cards).
80Flags are set to 0 for cards not using a secondary
81.Tn DMA
82channel, or to 0x10 + C to specify channel C.
83.Pp
84The driver works best with
85.Tn WSS/MSS
86cards, which have a very clean
87architecture and an orthogonal set of features.
88They also happen to be
89among the cheapest audio cards on the market.
90.Pp
91The driver does its best to recognize the installed hardware and drive
92it correctly so the user is not required to add several lines in
93.Pa /boot/device.hints .
94For
95.Tn PCI
96and
97.Tn ISA
98.Tn PnP
99cards this is actually easy
100since they identify themselves.
101For legacy
102.Tn ISA
103cards, the driver looks for
104.Tn MSS
105cards at addresses 0x530 and 0x604 (unless overridden
106in
107.Pa /boot/device.hints ) .
108.Ss Boot Variables
109In general, the module
110.Pa snd_foo
111corresponds to
112.Cd "device foo"
113and can be
114loaded by the boot
115.Xr loader 8
116via
117.Xr loader.conf 5
118or from the command line using the
119.Xr kldload 8
120utility.
121Options which can be specified in
122.Pa /boot/loader.conf
123include:
124.Bl -tag -width ".Va snd_emu10k1_load" -offset indent
125.It Va snd_driver_load
126.Pq Dq Li NO
127If set to
128.Dq Li YES ,
129this option loads all available drivers.
130.It Va snd_emu10k1_load
131.Pq Dq Li NO
132If set to
133.Dq Li YES ,
134only the SoundBlaster 5.1 driver and dependent modules will be loaded.
135.It Va snd_foo_load
136.Pq Dq Li NO
137If set to
138.Dq Li YES ,
139load driver for card/chipset foo.
140.El
141.Pp
142To define default values for the different mixer channels,
143set the channel to the prefered value using hints, e.g.:
144.Va hint.pcm.0.line Ns = Ns Qq Li 0 .
145This will mute the input channel per default.
146.Ss VCHANs
147Each device can optionally support more playback channels
148that physical hardware provides by using
149.Dq virtual channels
150or
151.Tn VCHANs .
152.Tn VCHAN
153options can be configured via the
154.Xr sysctl 8
155interface but can only be manipulated while the device is inactive.
156.Ss Runtime Configuration
157The following
158.Xr sysctl 8
159variables are available:
160.Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent
161.It Va hw.snd.pcm%d.buffersize
162Configure the amount of
163.Tn DMA
164bufferspace available for a device.
165.It Va hw.snd.targetirqrate
166Set the default block size such that continuous
167playback will achieve this
168.Tn IRQ
169rate.
170This value can be tuned to improve application performance.
171Increase this value when the sound lags and decrease
172it if sound stutters or breaks up.
173.It Va hw.snd.unit
174When using
175.Xr devfs 5 ,
176the default device for
177.Pa /dev/dsp .
178Equivalent to a symlink from
179.Pa /dev/dsp
180to
181.Pa /dev/dsp Ns Va ${hw.snd.unit} .
182.It Va hw.snd.report_soft_formats
183Controls the internal format conversion if it is
184available transparently to the application software.
185When disabled or not available, the application will
186only be able to select formats the device natively supports.
187.It Va hw.snd.verbose
188Level of verbosity for the
189.Pa /dev/sndstat
190device.
191Higher values include more output and the highest level,
192three, should be used when reporting problems.
193Other options include:
194.Bl -tag -width 2n
195.It 0
196Installed devices and their allocated bus resources.
197.It 1
198The number of playback, record, virtual channels, and
199flags per device.
200.It 2
201Channel information per device including the channel's
202current format, speed, and pseudo device statistics such as
203buffer overruns and buffer underruns.
204.It 3
205File names and versions of the currently sound loaded modules.
206.El
207.It Va hw.snd.maxautovchans
208Global
209.Tn VCHAN
210setting that only affects devices that have only one playback channel.
211The sound system will dynamically create up this many
212.Tn VCHANs .
213Set to
214.Dq 0
215if no
216.Tn VCHANS
217are desired.
218.It Va hw.snd.pcm%d.vchans
219The current number of
220.Tn VCHANs
221allocated per device.
222This can be set to preallocate a certain number of
223.Tn VCHANs .
224Setting this value to
225.Dq 0
226will disable
227.Tn VCHANs
228for this device.
229.El
230.Ss Recording Channels
231On devices that have more than one recording source (ie: mic and line),
232there is a corresponding
233.Pa /dev/dspr%d.%d
234device.
235.Ss Statistics
236Channel statistics are only kept while the device is open.
237So with situations involving overruns and underruns, consider the output
238while the errant application is open and running.
239.Ss IOCTL Support
240The driver supports most of the
241.Tn OSS
242.Fn ioctl
243functions, and most applications work unmodified.
244A few differences exist, while memory mapped playback is
245supported natively and in
246.Tn Linux
247emulation, memory mapped recording is
248not due to
249.Tn VM
250system design.
251As a consequence, some applications may need to be recompiled
252with a slightly modified audio module.
253See
254.In sys/soundcard.h
255for a complete list of the supported
256.Fn ioctl
257functions.
258.Ss Supported Cards
259Below we include a list of supported codecs/cards.
260If your sound card
261is not listed here, it may be supported by a bridge driver.
262.Bl -tag -width 2m
263.It CS4237, CS4236, CS4232, CS4231 (ISA)
264All these cards work perfectly in full duplex using the MSS mode.
265This chipset is used, among others, on the A/Open AW35 and AW32, on
266some Intel motherboards, and (the CS4231) on some non-PnP cards.
267.Pp
268The CS4232 is reported as buggy in the Voxware documentation but
269I am not sure if this is true.
270On one of my Intel motherboards,
271capture does not work simply because the capture DMA channel is
272not wired to the ISA DMA controller.
273.It Yamaha OPL-SAx (ISA)
274Works perfectly in all modes.
275This chip is used in several PnP cards,
276but also (in non-PnP mode) on motherboards and laptops (e.g., the
277Toshiba Libretto).
278.It OPTi931 (ISA)
279The chip is buggy, but the driver has many workarounds to make it work
280in full duplex because for some time these were the only full duplex
281cards I could find.
282U-law format uses U8 format internally because of
283a bug in the chip.
284.It Trident 4DWave DX/NX (PCI)
285.It ENSONIQ AudioPCI ES1370/1371 (PCI)
286Creative Labs SoundBlaster PCI is supported as well.
287.It ESS Solo-1/1E (PCI)
288.It NeoMagic 256AV/ZX (PCI)
289.El
290.Sh FILES
291The
292.Nm
293drivers may create the following
294device nodes:
295.Pp
296.Bl -tag -width ".Pa /dev/audio%d.%d" -compact
297.It Pa /dev/audio%d.%d
298Sparc-compatible audio device.
299.It Pa /dev/dsp%d.%d
300Digitized voice device.
301.It Pa /dev/dspW%d.%d
302Like
303.Pa /dev/dsp ,
304but 16 bits per sample.
305.It Pa /dev/dspr%d.%d
306Should be connected to a record codec.
307.It Pa /dev/sndstat
308Current
309.Nm
310status, including all channels and drivers.
311.El
312.Pp
313The first number in the device node
314represents the unit number of the
315.Nm
316device.
317All
318.Nm
319devices are listed
320in
321.Pa /dev/sndstat .
322Additional messages are sometimes recorded when the
323device is probed and attached, these messages can be viewed with the
324.Xr dmesg 8
325utility.
326.Sh DIAGNOSTICS
327.Bl -diag
328.It ac97: dac not ready
329AC97 codec is not likely to be accompanied with the sound card.
330.It unsupported subdevice XX
331A device node is not created properly.
332.El
333.Sh BUGS
334Some features of your cards (e.g., global volume control) might not
335be supported on all devices.
336.Sh HISTORY
337The
338.Nm
339device driver first appeared in
340.Fx 2.2.6
341written by
342.An Luigi Rizzo .
343It was later
344rewritten in
345.Fx 4.0
346by
347.An Cameron Grant .
348The API evolved from the VOXWARE
349standard which later became OSS standard.
350.Sh SEE ALSO
351.Xr csa 4 ,
352.Xr gusc 4 ,
353.Xr sbc 4 ,
354.Xr devfs 5 ,
355.Xr loader.conf 5 ,
356.Xr dmesg 8 ,
357.Xr kldload 8 ,
358.Xr sysctl 8
359.Rs
360.%T "The OSS API"
361.%O "http://www.opensound.com/pguide/oss.pdf"
362.Re
363.Sh AUTHORS
364.An -nosplit
365.An Luigi Rizzo Aq luigi@iet.unipi.it
366initially wrote the
367.Nm
368device driver and this manual page.
369.An Cameron Grant Aq gandalf@vilnya.demon.co.uk
370later revised the device driver for
371.Fx 4.0 .
372.An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
373revised this manual page.
374It was then rewritten for
375.Fx 5.2 .
|