xref: /freebsd/share/man/man4/pcm.4 (revision 52267f7411adcc76ede961420e08c0e42f42d415)
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 23, 2007
29.Dt SOUND 4
30.Os
31.Sh NAME
32.Nm sound ,
33.Nm pcm ,
34.Nm snd
35.Nd
36.Fx
37PCM audio device infrastructure
38.Sh SYNOPSIS
39To compile this driver into the kernel, place the following line in your
40kernel configuration file:
41.Bd -ragged -offset indent
42.Cd "device sound"
43.Ed
44.Pp
45Non-PnP sound cards require the following lines in
46.Xr device.hints 5 :
47.Bd -literal -offset indent
48hint.pcm.0.at="isa"
49hint.pcm.0.irq="5"
50hint.pcm.0.drq="1"
51hint.pcm.0.flags="0x0"
52.Ed
53.Sh DESCRIPTION
54.Bf -emphasis
55Note: There exists some ambiguity in the naming at the moment
56.Pq Nm sound , pcm , snd .
57It will be resolved soon by renaming
58.Cd "device sound"
59to
60.Cd "device snd" ,
61and doing associated changes.
62.Ef
63.Pp
64The
65.Nm
66driver provides support for
67.Tn PCM
68audio play and capture.
69This driver also supports various
70.Tn PCI ,
71.Tn ISA ,
72.Tn WSS/MSS
73compatible
74sound cards, AC97 mixer and High Definition Audio.
75Once the
76.Nm
77driver attaches, supported devices provide audio record and
78playback channels.
79The
80.Fx
81sound system provides dynamic mixing
82.Dq VCHAN
83and rate conversion
84.Dq soft formats .
85True full duplex operation is available on most sound cards.
86.Pp
87If the sound card is supported by a bridge driver, the
88.Nm
89driver works in conjunction with the bridge driver.
90.Pp
91Apart from the usual parameters, the flags field is used to specify
92the secondary
93.Tn DMA
94channel (generally used for capture in full duplex cards).
95Flags are set to 0 for cards not using a secondary
96.Tn DMA
97channel, or to 0x10 + C to specify channel C.
98.Pp
99The driver does its best to recognize the installed hardware and drive
100it correctly so the user is not required to add several lines in
101.Pa /boot/device.hints .
102For
103.Tn PCI
104and
105.Tn ISA
106.Tn PnP
107cards this is actually easy
108since they identify themselves.
109For legacy
110.Tn ISA
111cards, the driver looks for
112.Tn MSS
113cards at addresses 0x530 and 0x604 (unless overridden
114in
115.Pa /boot/device.hints ) .
116.Ss Boot Variables
117In general, the module
118.Pa snd_foo
119corresponds to
120.Cd "device snd_foo"
121and can be
122loaded by the boot
123.Xr loader 8
124via
125.Xr loader.conf 5
126or from the command line using the
127.Xr kldload 8
128utility.
129Options which can be specified in
130.Pa /boot/loader.conf
131include:
132.Bl -tag -width ".Va snd_emu10k1_load" -offset indent
133.It Va snd_driver_load
134.Pq Dq Li NO
135If set to
136.Dq Li YES ,
137this option loads all available drivers.
138.It Va snd_emu10k1_load
139.Pq Dq Li NO
140If set to
141.Dq Li YES ,
142only the SoundBlaster 5.1 driver and dependent modules will be loaded.
143.It Va snd_foo_load
144.Pq Dq Li NO
145If set to
146.Dq Li YES ,
147load driver for card/chipset foo.
148.El
149.Pp
150To define default values for the different mixer channels,
151set the channel to the preferred value using hints, e.g.:
152.Va hint.pcm.0.line Ns = Ns Qq Li 0 .
153This will mute the input channel per default.
154.Ss VCHANs
155Each device can optionally support more playback and recording channels
156than physical hardware provides by using
157.Dq virtual channels
158or
159.Tn VCHANs .
160.Tn VCHAN
161options can be configured via the
162.Xr sysctl 8
163interface but can only be manipulated while the device is inactive.
164.Ss Runtime Configuration
165There are a number of
166.Xr sysctl 8
167variables available.
168.Va hw.snd.*
169tunables are global settings and
170.Va dev.pcm.*
171are device specific.
172.Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent
173.It Va hw.snd.latency_profile
174Define sets of buffering latency conversion tables for the
175.Va hw.snd.latency
176tunable.
177A value of 0 will use a low and aggressive latency profile which can result
178in possible underruns if the application cannot keep up with a rapid irq
179rate, especially during high workload.
180The default value is 1, which is considered a moderate/safe latency profile.
181.It Va hw.snd.latency
182Configure the buffering latency.
183Only affects applications that do not explicitly request
184blocksize / fragments.
185This tunable provides finer granularity than the
186.Va hw.snd.latency_profile
187tunable.
188Possible values range between 0 (lowest latency) and 10 (highest latency).
189.It Va hw.snd.report_soft_formats
190Controls the internal format conversion if it is
191available transparently to the application software.
192When disabled or not available, the application will
193only be able to select formats the device natively supports.
194.It Va hw.snd.compat_linux_mmap
195Enable to allow PROT_EXEC page mappings.
196All Linux applications using sound and
197.Xr mmap 2
198require this.
199.It Va hw.snd.feeder_rate_round
200Sample rate rounding threshold, to avoid large prime division at the
201cost of accuracy.
202All requested sample rates will be rounded to the nearest threshold value.
203Possible values range between 0 (disabled) and 500.
204Default is 25.
205.It Va hw.snd.feeder_rate_max
206Maximum allowable sample rate.
207.It Va hw.snd.feeder_rate_min
208Minimum allowable sample rate.
209.It Va hw.snd.verbose
210Level of verbosity for the
211.Pa /dev/sndstat
212device.
213Higher values include more output and the highest level,
214four, should be used when reporting problems.
215Other options include:
216.Bl -tag -width 2n
217.It 0
218Installed devices and their allocated bus resources.
219.It 1
220The number of playback, record, virtual channels, and
221flags per device.
222.It 2
223Channel information per device including the channel's
224current format, speed, and pseudo device statistics such as
225buffer overruns and buffer underruns.
226.It 3
227File names and versions of the currently loaded sound modules.
228.It 4
229Various messages intended for debugging.
230.El
231.It Va hw.snd.maxautovchans
232Global
233.Tn VCHAN
234setting that only affects devices with at least one playback or recording channel available.
235The sound system will dynamically create up this many
236.Tn VCHANs .
237Set to
238.Dq 0
239if no
240.Tn VCHANS
241are desired.
242Maximum value is 256.
243.It Va hw.snd.default_unit
244Default sound card for systems with multiple sound cards.
245When using
246.Xr devfs 5 ,
247the default device for
248.Pa /dev/dsp .
249Equivalent to a symlink from
250.Pa /dev/dsp
251to
252.Pa /dev/dsp Ns Va ${hw.snd.default_unit} .
253.It Va hw.snd.default_auto
254Enable to automatically assign default sound unit to the most recent
255attached device.
256.It Va dev.pcm.%d.[play|rec].vchans
257The current number of
258.Tn VCHANs
259allocated per device.
260This can be set to preallocate a certain number of
261.Tn VCHANs .
262Setting this value to
263.Dq 0
264will disable
265.Tn VCHANs
266for this device.
267.It Va dev.pcm.%d.[play|rec].vchanrate
268Sample rate speed for
269.Tn VCHAN
270mixing.
271All playback paths will be converted to this sample rate before the mixing
272process begins.
273.It Va dev.pcm.%d.[play|rec].vchanformat
274Format for
275.Tn VCHAN
276mixing.
277All playback paths will be converted to this format before the mixing
278process begins.
279.It Va dev.pcm.%d.polling
280Experimental polling mode support where the driver operates by querying the
281device state on each tick using a
282.Xr callout 9
283mechanism.
284Disabled by default and currently only available for a few device drivers.
285.El
286.Ss Recording Channels
287On devices that have more than one recording source (ie: mic and line),
288there is a corresponding
289.Pa /dev/dsp%d.r%d
290device.
291.Ss Statistics
292Channel statistics are only kept while the device is open.
293So with situations involving overruns and underruns, consider the output
294while the errant application is open and running.
295.Ss IOCTL Support
296The driver supports most of the
297.Tn OSS
298.Fn ioctl
299functions, and most applications work unmodified.
300A few differences exist, while memory mapped playback is
301supported natively and in
302.Tn Linux
303emulation, memory mapped recording is
304not due to
305.Tn VM
306system design.
307As a consequence, some applications may need to be recompiled
308with a slightly modified audio module.
309See
310.In sys/soundcard.h
311for a complete list of the supported
312.Fn ioctl
313functions.
314.Sh FILES
315The
316.Nm
317drivers may create the following
318device nodes:
319.Pp
320.Bl -tag -width ".Pa /dev/audio%d.%d" -compact
321.It Pa /dev/audio%d.%d
322Sparc-compatible audio device.
323.It Pa /dev/dsp%d.%d
324Digitized voice device.
325.It Pa /dev/dspW%d.%d
326Like
327.Pa /dev/dsp ,
328but 16 bits per sample.
329.It Pa /dev/dsp%d.p%d
330Playback channel.
331.It Pa /dev/dsp%d.r%d
332Record channel.
333.It Pa /dev/dsp%d.vp%d
334Virtual playback channel.
335.It Pa /dev/dsp%d.vr%d
336Virtual recording channel.
337.It Pa /dev/sndstat
338Current
339.Nm
340status, including all channels and drivers.
341.El
342.Pp
343The first number in the device node
344represents the unit number of the
345.Nm
346device.
347All
348.Nm
349devices are listed
350in
351.Pa /dev/sndstat .
352Additional messages are sometimes recorded when the
353device is probed and attached, these messages can be viewed with the
354.Xr dmesg 8
355utility.
356.Pp
357The above device nodes are only created on demand through the dynamic
358.Xr devfs 5
359clone handler.
360Users are strongly discouraged to access them directly.
361For specific sound card access, please instead use
362.Pa /dev/dsp
363or
364.Pa /dev/dsp%d .
365.Sh DIAGNOSTICS
366.Bl -diag
367.It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead
368The hardware does not generate interrupts to serve incoming (play)
369or outgoing (record) data.
370.It unsupported subdevice XX
371A device node is not created properly.
372.El
373.Sh SEE ALSO
374.Xr snd_ad1816 4 ,
375.Xr snd_als4000 4 ,
376.Xr snd_atiixp 4 ,
377.Xr snd_audiocs 4 ,
378.Xr snd_cmi 4 ,
379.Xr snd_cs4281 4 ,
380.Xr snd_csa 4 ,
381.Xr snd_ds1 4 ,
382.Xr snd_emu10k1 4 ,
383.Xr snd_emu10kx 4 ,
384.Xr snd_envy24 4 ,
385.Xr snd_envy24ht 4 ,
386.Xr snd_es137x 4 ,
387.Xr snd_ess 4 ,
388.Xr snd_fm801 4 ,
389.Xr snd_gusc 4 ,
390.Xr snd_hda 4 ,
391.Xr snd_ich 4 ,
392.Xr snd_maestro 4 ,
393.Xr snd_maestro3 4 ,
394.Xr snd_mss 4 ,
395.Xr snd_neomagic 4 ,
396.Xr snd_sbc 4 ,
397.Xr snd_solo 4 ,
398.Xr snd_spicds 4 ,
399.Xr snd_t4dwave 4 ,
400.Xr snd_uaudio 4 ,
401.Xr snd_via8233 4 ,
402.Xr snd_via82c686 4 ,
403.Xr snd_vibes 4 ,
404.Xr devfs 5 ,
405.Xr device.hints 5 ,
406.Xr loader.conf 5 ,
407.Xr dmesg 8 ,
408.Xr kldload 8 ,
409.Xr sysctl 8
410.Rs
411.%T "The OSS API"
412.%O "http://www.opensound.com/pguide/oss.pdf"
413.Re
414.Sh HISTORY
415The
416.Nm
417device driver first appeared in
418.Fx 2.2.6
419as
420.Nm pcm ,
421written by
422.An Luigi Rizzo .
423It was later
424rewritten in
425.Fx 4.0
426by
427.An Cameron Grant .
428The API evolved from the VOXWARE
429standard which later became OSS standard.
430.Sh AUTHORS
431.An -nosplit
432.An Luigi Rizzo Aq luigi@iet.unipi.it
433initially wrote the
434.Nm pcm
435device driver and this manual page.
436.An Cameron Grant Aq gandalf@vilnya.demon.co.uk
437later revised the device driver for
438.Fx 4.0 .
439.An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
440revised this manual page.
441It was then rewritten for
442.Fx 5.2 .
443.Sh BUGS
444Some features of your sound card (e.g., global volume control) might not
445be supported on all devices.
446