Don't use macros which expand to some text (such as .Dx) in the short
[dragonfly.git] / 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.39.2.6 2007/05/23 19:45:49 brueffer Exp $
27 .\" $DragonFly: src/share/man/man4/pcm.4,v 1.8 2007/12/13 20:51:36 swildner Exp $
28 .\"
29 .Dd November 26, 2006
30 .Dt SOUND 4
31 .Os
32 .Sh NAME
33 .Nm sound ,
34 .Nm pcm ,
35 .Nm snd
36 .Nd DragonFly PCM audio device infrastructure
37 .Sh SYNOPSIS
38 To compile this driver into the kernel, place the following line in your
39 kernel configuration file:
40 .Bd -ragged -offset indent
41 .Cd "device pcm"
42 .Ed
43 .Pp
44 For non-PnP sound cards:
45 .Bd -literal -offset indent
46 .Cd "device pcm0 at isa? port? irq 5 drq 1 flags 0x15"
47 .Ed
48 .Sh DESCRIPTION
49 The
50 .Nm
51 driver provides support for
52 .Tn PCM
53 audio play and capture.
54 This driver also supports various
55 .Tn PCI ,
56 .Tn ISA ,
57 .Tn WSS/MSS
58 compatible
59 sound cards, AC97 mixer and High Definition Audio.
60 Once the
61 .Nm
62 driver attaches, supported devices provide audio record and
63 playback channels.
64 The
65 .Dx
66 sound system provides dynamic mixing
67 .Dq VCHAN
68 and rate conversion
69 .Dq soft formats .
70 True full duplex operation is available on most sound cards.
71 .Pp
72 If the sound card is supported by a bridge driver, the
73 .Nm
74 driver works in conjunction with the bridge driver.
75 .Pp
76 Apart from the usual parameters, the flags field is used to specify
77 the secondary
78 .Tn DMA
79 channel (generally used for capture in full duplex cards).
80 Flags are set to 0 for cards not using a secondary
81 .Tn DMA
82 channel, or to 0x10 + C to specify channel C.
83 .Pp
84 The driver does its best to recognize the installed hardware and drive
85 it correctly so the user is not required to add specific settings to
86 the kernel config file.
87 For
88 .Tn PCI
89 and
90 .Tn ISA
91 .Tn PnP
92 cards this is actually easy
93 since they identify themselves.
94 For legacy
95 .Tn ISA
96 cards, the driver looks for
97 .Tn MSS
98 cards at addresses 0x530 and 0x604 (unless overridden
99 in the kernel config file ) .
100 .Ss Boot Variables
101 In general, the module
102 .Pa snd_foo
103 corresponds to
104 .Cd "device snd_foo"
105 and can be
106 loaded by the boot
107 .Xr loader 8
108 via
109 .Xr loader.conf 5
110 or from the command line using the
111 .Xr kldload 8
112 utility.
113 Options which can be specified in
114 .Pa /boot/loader.conf
115 include:
116 .Bl -tag -width ".Va snd_emu10k1_load" -offset indent
117 .It Va snd_driver_load
118 .Pq Dq Li NO
119 If set to
120 .Dq Li YES ,
121 this option loads all available drivers.
122 .It Va snd_emu10k1_load
123 .Pq Dq Li NO
124 If set to
125 .Dq Li YES ,
126 only the SoundBlaster 5.1 driver and dependent modules will be loaded.
127 .It Va snd_foo_load
128 .Pq Dq Li NO
129 If set to
130 .Dq Li YES ,
131 load driver for card/chipset foo.
132 .El
133 .Ss VCHANs
134 Each device can optionally support more playback channels
135 than physical hardware provides by using
136 .Dq virtual channels
137 or
138 .Tn VCHANs .
139 .Tn VCHAN
140 options can be configured via the
141 .Xr sysctl 8
142 interface but can only be manipulated while the device is inactive.
143 .Ss Runtime Configuration
144 The following
145 .Xr sysctl 8
146 variables are available:
147 .Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent
148 .It Va hw.snd.pcm%d.buffersize
149 Configure the amount of
150 .Tn DMA
151 bufferspace available for a device.
152 .It Va hw.snd.targetirqrate
153 Set the default block size such that continuous
154 playback will achieve this
155 .Tn IRQ
156 rate.
157 This value can be tuned to improve application performance.
158 Increase this value when the sound lags and decrease
159 it if sound stutters or breaks up.
160 .It Va hw.snd.report_soft_formats
161 Controls the internal format conversion if it is
162 available transparently to the application software.
163 When disabled or not available, the application will
164 only be able to select formats the device natively supports.
165 .It Va hw.snd.verbose
166 Level of verbosity for the
167 .Pa /dev/sndstat
168 device.
169 Higher values include more output and the highest level,
170 three, should be used when reporting problems.
171 Other options include:
172 .Bl -tag -width 2n
173 .It 0
174 Installed devices and their allocated bus resources.
175 .It 1
176 The number of playback, record, virtual channels, and
177 flags per device.
178 .It 2
179 Channel information per device including the channel's
180 current format, speed, and pseudo device statistics such as
181 buffer overruns and buffer underruns.
182 .It 3
183 File names and versions of the currently loaded sound modules.
184 .El
185 .It Va hw.snd.maxautovchans
186 Global
187 .Tn VCHAN
188 setting that only affects devices with only one playback channel available.
189 The sound system will dynamically create up this many
190 .Tn VCHANs .
191 Set to
192 .Dq 0
193 if no
194 .Tn VCHANS
195 are desired.
196 .It Va hw.snd.pcm%d.vchans
197 The current number of
198 .Tn VCHANs
199 allocated per device.
200 This can be set to preallocate a certain number of
201 .Tn VCHANs .
202 Setting this value to
203 .Dq 0
204 will disable
205 .Tn VCHANs
206 for this device.
207 .El
208 .Ss Recording Channels
209 On devices that have more than one recording source (ie: mic and line),
210 there is a corresponding
211 .Pa /dev/dspr%d.%d
212 device.
213 .Ss Statistics
214 Channel statistics are only kept while the device is open.
215 So with situations involving overruns and underruns, consider the output
216 while the errant application is open and running.
217 .Ss IOCTL Support
218 The driver supports most of the
219 .Tn OSS
220 .Fn ioctl
221 functions, and most applications work unmodified.
222 A few differences exist, while memory mapped playback is
223 supported natively and in
224 .Tn Linux
225 emulation, memory mapped recording is
226 not due to
227 .Tn VM
228 system design.
229 As a consequence, some applications may need to be recompiled
230 with a slightly modified audio module.
231 See
232 .In sys/soundcard.h
233 for a complete list of the supported
234 .Fn ioctl
235 functions.
236 .Sh FILES
237 The
238 .Nm
239 drivers may use the following
240 device nodes:
241 .Pp
242 .Bl -tag -width ".Pa /dev/audio%d.%d" -compact
243 .It Pa /dev/audio%d.%d
244 Sparc-compatible audio device.
245 .It Pa /dev/dsp%d.%d
246 Digitized voice device.
247 .It Pa /dev/dspW%d.%d
248 Like
249 .Pa /dev/dsp ,
250 but 16 bits per sample.
251 .It Pa /dev/dspr%d.%d
252 Should be connected to a record codec.
253 .It Pa /dev/sndstat
254 Current
255 .Nm
256 status, including all channels and drivers.
257 .El
258 .Pp
259 The first number in the device node
260 represents the unit number of the
261 .Nm
262 device.
263 All
264 .Nm
265 devices are listed
266 in
267 .Pa /dev/sndstat .
268 Additional messages are sometimes recorded when the
269 device is probed and attached, these messages can be viewed with the
270 .Xr dmesg 8
271 utility.
272 .Sh DIAGNOSTICS
273 .Bl -diag
274 .It ac97: dac not ready
275 AC97 codec is not likely to be accompanied with the sound card.
276 .It unsupported subdevice XX
277 A device node is not created properly.
278 .El
279 .Sh SEE ALSO
280 .Xr snd_ad1816 4 ,
281 .Xr snd_als4000 4 ,
282 .Xr snd_atiixp 4 ,
283 .Xr snd_cmi 4 ,
284 .Xr snd_cs4281 4 ,
285 .Xr snd_csa 4 ,
286 .Xr snd_ds1 4 ,
287 .Xr snd_emu10k1 4 ,
288 .Xr snd_envy24 4 ,
289 .Xr snd_envy24ht 4 ,
290 .Xr snd_es137x 4 ,
291 .Xr snd_ess 4 ,
292 .Xr snd_fm801 4 ,
293 .Xr snd_gusc 4 ,
294 .Xr snd_hda 4 ,
295 .Xr snd_ich 4 ,
296 .Xr snd_maestro 4 ,
297 .Xr snd_maestro3 4 ,
298 .Xr snd_mss 4 ,
299 .Xr snd_neomagic 4 ,
300 .Xr snd_sbc 4 ,
301 .Xr snd_solo 4 ,
302 .Xr snd_spicds 4 ,
303 .Xr snd_t4dwave 4 ,
304 .Xr snd_uaudio 4 ,
305 .Xr snd_via8233 4 ,
306 .Xr snd_via82c686 4 ,
307 .Xr snd_vibes 4 ,
308 .Xr loader.conf 5 ,
309 .Xr dmesg 8 ,
310 .Xr kldload 8 ,
311 .Xr sysctl 8
312 .Rs
313 .%T "The OSS API"
314 .%O "http://www.opensound.com/pguide/oss.pdf"
315 .Re
316 .Sh HISTORY
317 The
318 .Nm
319 device driver first appeared in
320 .Fx 2.2.6
321 as
322 .Nm pcm ,
323 written by
324 .An Luigi Rizzo .
325 It was later
326 rewritten in
327 .Fx 4.0
328 by
329 .An Cameron Grant .
330 The API evolved from the VOXWARE
331 standard which later became OSS standard.
332 .Sh AUTHORS
333 .An -nosplit
334 .An Luigi Rizzo Aq luigi@iet.unipi.it
335 initially wrote the
336 .Nm pcm
337 device driver and this manual page.
338 .An Cameron Grant Aq gandalf@vilnya.demon.co.uk
339 later revised the device driver for
340 .Fx 4.0 .
341 .An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
342 revised this manual page.
343 It was then rewritten for
344 .Fx 5.2 .
345 .Sh BUGS
346 Some features of your sound card (e.g., global volume control) might not
347 be supported on all devices.