From owner-svn-src-all@FreeBSD.ORG Sat Jul 30 23:09:53 2011 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 30A761065675; Sat, 30 Jul 2011 23:09:53 +0000 (UTC) (envelope-from joel@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 1F87F8FC1E; Sat, 30 Jul 2011 23:09:53 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id p6UN9r3M019323; Sat, 30 Jul 2011 23:09:53 GMT (envelope-from joel@svn.freebsd.org) Received: (from joel@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id p6UN9rhJ019321; Sat, 30 Jul 2011 23:09:53 GMT (envelope-from joel@svn.freebsd.org) Message-Id: <201107302309.p6UN9rhJ019321@svn.freebsd.org> From: Joel Dahl Date: Sat, 30 Jul 2011 23:09:52 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r224533 - head/share/man/man4 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 30 Jul 2011 23:09:53 -0000 Author: joel (doc committer) Date: Sat Jul 30 23:09:52 2011 New Revision: 224533 URL: http://svn.freebsd.org/changeset/base/224533 Log: Add a better description, a few examples and a couple of minor fixes. Reviewed by: brueffer Approved by: re (kib) Modified: head/share/man/man4/pcm.4 Modified: head/share/man/man4/pcm.4 ============================================================================== --- head/share/man/man4/pcm.4 Sat Jul 30 22:57:38 2011 (r224532) +++ head/share/man/man4/pcm.4 Sat Jul 30 23:09:52 2011 (r224533) @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 13, 2009 +.Dd July 31, 2011 .Dt SOUND 4 .Os .Sh NAME @@ -41,7 +41,121 @@ kernel configuration file: .Bd -ragged -offset indent .Cd "device sound" .Ed +.Sh DESCRIPTION +The +.Nm +driver is the main component of the +.Fx sound system. +It works in conjunction with a bridge device driver on supported devices +and provides PCM audio record and playback once it attaches. +Each bridge device driver supports a specific set of audio chipsets and +needs to be enabled together with the +.Nm +driver. +PCI and ISA PnP audio devices identify themselves so users are usually not +required to add anything to +.Pa /boot/device.hints . +.Pp +Some of the main features of the +.Nm +driver are: multichannel audio, per-application +volume control, dynamic mixing through virtual sound channels, true full +duplex operation, bit perfect audio, rate conversion and low latency +modes. +.Pp +The +.Nm +driver is enabled by default, along with several bridge device drivers. +Those not enabled by default can be loaded during runtime with +.Xr kldload 8 +or during boot via +.Xr loader.conf 5 . +The following bridge device drivers are available: .Pp +.Bl -bullet -compact +.It +.Xr snd_ad1816 4 +.It +.Xr snd_ai2s 4 (enabled by default on powerpc) +.It +.Xr snd_als4000 4 +.It +.Xr snd_atiixp 4 +.It +.Xr snd_audiocs 4 (enabled by default on sparc64) +.It +.Xr snd_cmi 4 +.It +.Xr snd_cs4281 4 +.It +.Xr snd_csa 4 +.It +.Xr snd_davbus 4 (enabled by default on powerpc) +.It +.Xr snd_ds1 4 +.It +.Xr snd_emu10k1 4 +.It +.Xr snd_emu10kx 4 +.It +.Xr snd_envy24 4 +.It +.Xr snd_envy24ht 4 +.It +.Xr snd_es137x 4 (enabled by default on amd64, i386, sparc64) +.It +.Xr snd_ess 4 +.It +.Xr snd_fm801 4 +.It +.Xr snd_gusc 4 +.It +.Xr snd_hda 4 (enabled by default on amd64, i386) +.It +.Xr snd_ich 4 (enabled by default on amd64, i386) +.It +.Xr snd_maestro 4 +.It +.Xr snd_maestro3 4 +.It +.Xr snd_mss 4 +.It +.Xr snd_neomagic 4 +.It +snd_sb16 +.It +snd_sb8 +.It +.Xr snd_sbc 4 +.It +.Xr snd_solo 4 +.It +.Xr snd_spicds 4 +.It +.Xr snd_t4dwave 4 (enabled by default on sparc64) +.It +.Xr snd_uaudio 4 (enabled by default on amd64, i386, powerpc, sparc64) +.It +.Xr snd_via8233 4 (enabled by default on amd64, i386) +.It +.Xr snd_via82c686 4 +.It +.Xr snd_vibes 4 +.El +.Pp +Refer to the manual page for each bridge device driver for driver specific +settings and information. +.Ss Legacy Hardware +For old legacy +.Tn ISA +cards, the driver looks for +.Tn MSS +cards at addresses +.Dv 0x530 +and +.Dv 0x604 . +These values can be overridden in +.Pa /boot/device.hints . Non-PnP sound cards require the following lines in .Xr device.hints 5 : .Bd -literal -offset indent @@ -50,33 +164,6 @@ hint.pcm.0.irq="5" hint.pcm.0.drq="1" hint.pcm.0.flags="0x0" .Ed -.Sh DESCRIPTION -The -.Nm -driver provides support for -.Tn PCM -audio play and capture. -This driver also supports various -.Tn PCI , -.Tn ISA , -.Tn WSS/MSS -compatible -sound cards, AC97 mixer and High Definition Audio. -Once the -.Nm -driver attaches, supported devices provide audio record and -playback channels. -The -.Fx -sound system provides dynamic mixing -.Dq VCHAN -and rate conversion -.Dq soft formats . -True full duplex operation is available on most sound cards. -.Pp -If the sound card is supported by a bridge driver, the -.Nm -driver works in conjunction with the bridge driver. .Pp Apart from the usual parameters, the flags field is used to specify the secondary @@ -85,24 +172,6 @@ channel (generally used for capture in f Flags are set to 0 for cards not using a secondary .Tn DMA channel, or to 0x10 + C to specify channel C. -.Pp -The driver does its best to recognize the installed hardware and drive -it correctly so the user is not required to add several lines in -.Pa /boot/device.hints . -For -.Tn PCI -and -.Tn ISA -.Tn PnP -cards this is actually easy -since they identify themselves. -For legacy -.Tn ISA -cards, the driver looks for -.Tn MSS -cards at addresses 0x530 and 0x604 (unless overridden -in -.Pa /boot/device.hints ) . .Ss Boot Variables In general, the module .Pa snd_foo @@ -119,17 +188,18 @@ utility. Options which can be specified in .Pa /boot/loader.conf include: -.Bl -tag -width ".Va snd_emu10k1_load" -offset indent +.Bl -tag -width ".Va snd_driver_load" -offset indent .It Va snd_driver_load .Pq Dq Li NO If set to .Dq Li YES , this option loads all available drivers. -.It Va snd_emu10k1_load +.It Va snd_hda_load .Pq Dq Li NO If set to .Dq Li YES , -only the SoundBlaster 5.1 driver and dependent modules will be loaded. +only the Intel High Definition Audio bridge device driver and dependent +modules will be loaded. .It Va snd_foo_load .Pq Dq Li NO If set to @@ -155,8 +225,9 @@ This provides a base interface for relat support. Multichannel audio works both with and without .Tn VCHANs . -Most bridge device drivers are still missing multichannel matrixing support -, but in most cases this should be trivial to implement. +.Pp +Most bridge device drivers are still missing multichannel matrixing +support, but in most cases this should be trivial to implement. Use the .Va dev.pcm.%d.[play|rec].vchanformat .Xr sysctl(8) @@ -173,7 +244,7 @@ controls (bass and treble). Commonly used for ear-candy or frequency compensation due to the vast difference in hardware quality. EQ is disabled by default, but can be enabled with the -.Va hint.pcm. Ns Ao Ar X Ac Ns Va .eq +.Va hint.pcm.%d.eq tunable. .Ss VCHANs Each device can optionally support more playback and recording channels @@ -208,13 +279,13 @@ driver. The following tunables can not be changed during runtime using .Xr sysctl 8 . .Bl -tag -width indent -.It Va hint.pcm. Ns Ao Ar X Ac Ns Va .eq +.It Va hint.pcm.%d.eq Set to 1 or 0 to explicitly enable (1) or disable (0) the equalizer. Requires a driver reload if changed. Enabling this will make bass and treble controls appear in mixer applications. This tunable is undefined by default. Equalizing is disabled by default. -.It Va hint.pcm. Ns Ao Ar X Ac Ns Va .vpc +.It Va hint.pcm.%d.vpc Set to 1 or 0 to explicitly enable (1) or disable (0) the .Tn VPC feature. @@ -512,6 +583,9 @@ On devices that have more than one recor there is a corresponding .Pa /dev/dsp%d.r%d device. +The +.Xr mixer 8 +utility can be used to start and stop recording from an specific device. .Ss Statistics Channel statistics are only kept while the device is open. So with situations involving overruns and underruns, consider the output @@ -586,6 +660,31 @@ For specific sound card access, please i .Pa /dev/dsp or .Pa /dev/dsp%d . +.Sh EXAMPLES +Use the sound metadriver to load all +.Nm +bridge device drivers at once +(for example if it is unclear which the correct driver to use is): +.Pp +.Dl kldload snd_driver +.Pp +Load a specific bridge device driver, in this case the Intel +High Definition Audio driver: +.Pp +.Dl kldload snd_hda +.Pp +Check the status of all detected +.Nm +devices: +.Pp +.Dl cat /dev/sndstat +.Pp +Change the default sound device, in this case to the second device. +This is handy if there are multiple +.Nm +devices available: +.Pp +.Dl sysctl hw.snd.default_unit=1 .Sh DIAGNOSTICS .Bl -diag .It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead @@ -596,12 +695,14 @@ A device node is not created properly. .El .Sh SEE ALSO .Xr snd_ad1816 4 , +.Xr snd_ai2s 4 , .Xr snd_als4000 4 , .Xr snd_atiixp 4 , .Xr snd_audiocs 4 , .Xr snd_cmi 4 , .Xr snd_cs4281 4 , .Xr snd_csa 4 , +.Xr snd_davbus 4 , .Xr snd_ds1 4 , .Xr snd_emu10k1 4 , .Xr snd_emu10kx 4 , @@ -630,6 +731,7 @@ A device node is not created properly. .Xr loader.conf 5 , .Xr dmesg 8 , .Xr kldload 8 , +.Xr mixer 8 , .Xr sysctl 8 .Rs .%T "Cookbook formulae for audio EQ biquad filter coefficients, by Robert Bristow-Johnson"