From c2e4cdb2dad69b0a79e0f366b170b021a4cbd8f0 Mon Sep 17 00:00:00 2001 From: joel Date: Sun, 26 Nov 2006 12:27:02 +0000 Subject: - Update the Runtime Configuration, FILES and DIAGNOSTICS sections to the new world order. - Use our standard section 4 SYNOPSIS. - Minor nits. Reviewed by: brueffer, ariff --- share/man/man4/pcm.4 | 121 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 80 insertions(+), 41 deletions(-) (limited to 'share') diff --git a/share/man/man4/pcm.4 b/share/man/man4/pcm.4 index c41114a..4a709e1 100644 --- a/share/man/man4/pcm.4 +++ b/share/man/man4/pcm.4 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 14, 2006 +.Dd November 26, 2006 .Dt SOUND 4 .Os .Sh NAME @@ -36,13 +36,13 @@ .Fx PCM audio device infrastructure .Sh SYNOPSIS -For a card with bridge driver support, and a PnP card: +To compile this driver into the kernel, place the following line in your +kernel configuration file: .Bd -ragged -offset indent .Cd "device sound" .Ed .Pp -For a card without bridge driver support, and a non-PnP card, -the following lines may be required in +Non-PnP sound cards require the following lines in .Xr device.hints 5 : .Bd -literal -offset indent hint.pcm.0.at="isa" @@ -68,10 +68,10 @@ driver provides support for audio play and capture. This driver also supports various .Tn PCI , +.Tn ISA , .Tn WSS/MSS -compatible, -.Tn ISA -sound cards, and AC97 mixer. +compatible +sound cards, AC97 mixer and High Definition Audio. Once the .Nm driver attaches, supported devices provide audio record and @@ -82,7 +82,7 @@ sound system provides dynamic mixing .Dq VCHAN and rate conversion .Dq soft formats . -True full duplex operation is available on most cards. +True full duplex operation is available on most sound cards. .Pp If the sound card is supported by a bridge driver, the .Nm @@ -162,42 +162,51 @@ options can be configured via the .Xr sysctl 8 interface but can only be manipulated while the device is inactive. .Ss Runtime Configuration -The following +There are a number of .Xr sysctl 8 -variables are available: +variables available. +.Va hw.snd.* +tunables are global settings and +.Va dev.pcm.* +are device specific. .Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent -.It Va hw.snd.pcm%d.buffersize -Configure the amount of -.Tn DMA -bufferspace available for a device. -.It Va hw.snd.targetirqrate -Set the default block size such that continuous -playback will achieve this -.Tn IRQ -rate. -This value can be tuned to improve application performance. -Increase this value when the sound lags and decrease -it if sound stutters or breaks up. -.It Va hw.snd.unit -When using -.Xr devfs 5 , -the default device for -.Pa /dev/dsp . -Equivalent to a symlink from -.Pa /dev/dsp -to -.Pa /dev/dsp Ns Va ${hw.snd.unit} . +.It Va hw.snd.latency_profile +Define sets of buffering latency conversion tables for the +.Va hw.snd.latency +tunable. +A value of 0 will use a low and aggressive latency profile which can result +in possible underruns if the application cannot keep up with a rapid irq +rate, especially during high workload. +The default value is 1, which is considered a moderate/safe latency profile. +.It Va hw.snd.latency +Configure the buffering latency. +Only affects applications that do not explicitly request +blocksize / fragments. +This tunable provides finer granularity than the +.Va hw.snd.latency_profile +tunable. +Possible values range between 0 (lowest latency) and 10 (highest latency). .It Va hw.snd.report_soft_formats Controls the internal format conversion if it is available transparently to the application software. When disabled or not available, the application will only be able to select formats the device natively supports. +.It Va hw.snd.feeder_rate_round +Sample rate rounding threshold, to avoid large prime division at the +cost of accuracy. +All requested sample rates will be rounded to the nearest threshold value. +Possible values range between 0 (disabled) and 500. +Default is 25. +.It Va hw.snd.feeder_rate_max +Maximum allowable sample rate. +.It Va hw.snd.feeder_rate_min +Minimum allowable sample rate. .It Va hw.snd.verbose Level of verbosity for the .Pa /dev/sndstat device. Higher values include more output and the highest level, -three, should be used when reporting problems. +four, should be used when reporting problems. Other options include: .Bl -tag -width 2n .It 0 @@ -210,12 +219,14 @@ Channel information per device including the channel's current format, speed, and pseudo device statistics such as buffer overruns and buffer underruns. .It 3 -File names and versions of the currently sound loaded modules. +File names and versions of the currently loaded sound modules. +.It 4 +Various messages intended for debugging. .El .It Va hw.snd.maxautovchans Global .Tn VCHAN -setting that only affects devices that have only one playback channel. +setting that only affects devices with only one playback channel available. The sound system will dynamically create up this many .Tn VCHANs . Set to @@ -223,7 +234,18 @@ Set to if no .Tn VCHANS are desired. -.It Va hw.snd.pcm%d.vchans +Maximum value is 255. +.It Va hw.snd.default_unit +Default sound card for systems with multiple sound cards. +When using +.Xr devfs 5 , +the default device for +.Pa /dev/dsp . +Equivalent to a symlink from +.Pa /dev/dsp +to +.Pa /dev/dsp Ns Va ${hw.snd.default_unit} . +.It Va dev.pcm.%d.vchans The current number of .Tn VCHANs allocated per device. @@ -234,11 +256,23 @@ Setting this value to will disable .Tn VCHANs for this device. +.It Va dev.pcm.%d.vchanrate +Sample rate speed for +.Tn VCHAN +mixing. +All playback paths will be converted to this sample rate before the mixing +process begins. +.It Va dev.pcm.%d.vchanformat +Format for +.Tn VCHAN +mixing. +All playback paths will be converted to this format before the mixing +process begins. .El .Ss Recording Channels On devices that have more than one recording source (ie: mic and line), there is a corresponding -.Pa /dev/dspr%d.%d +.Pa /dev/dsp%d.r%d device. .Ss Statistics Channel statistics are only kept while the device is open. @@ -278,8 +312,12 @@ Digitized voice device. Like .Pa /dev/dsp , but 16 bits per sample. -.It Pa /dev/dspr%d.%d -Should be connected to a record codec. +.It Pa /dev/dsp%d.p%d +Playback channel. +.It Pa /dev/dsp%d.r%d +Record channel. +.It Pa /dev/dsp%d.v%d +Virtual channel. .It Pa /dev/sndstat Current .Nm @@ -301,8 +339,9 @@ device is probed and attached, these messages can be viewed with the utility. .Sh DIAGNOSTICS .Bl -diag -.It ac97: dac not ready -AC97 codec is not likely to be accompanied with the sound card. +.It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead +The hardware does not generate interrupts to serve incoming (play) +or outgoing (record) data. .It unsupported subdevice XX A device node is not created properly. .El @@ -377,5 +416,5 @@ revised this manual page. It was then rewritten for .Fx 5.2 . .Sh BUGS -Some features of your cards (e.g., global volume control) might not +Some features of your sound card (e.g., global volume control) might not be supported on all devices. -- cgit v1.1