Date: Thu, 06 Nov 2008 18:10:36 +0200 From: Giorgos Keramidas <keramida@ceid.upatras.gr> To: Alexander Motin <mav@freebsd.org> Cc: svn-src-head@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org Subject: Re: svn commit: r184695 - head/share/man/man4 Message-ID: <87r65okf7n.fsf@kobe.laptop> In-Reply-To: <200811051712.mA5HCIP7032611@svn.freebsd.org> (Alexander Motin's message of "Wed, 5 Nov 2008 17:12:18 %2B0000 (UTC)") References: <200811051712.mA5HCIP7032611@svn.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, 5 Nov 2008 17:12:18 +0000 (UTC), Alexander Motin <mav@freebsd.org> wrote: > Author: mav > Date: Wed Nov 5 17:12:18 2008 > New Revision: 184695 > URL: http://svn.freebsd.org/changeset/base/184695 > > Log: > Improve driver operation example description. > > Modified: > head/share/man/man4/snd_hda.4 Hi Alexander, There are a few places where we can probably improve the manpage a bit more. I am not sure I understand *all* the technical details of pins and association numbers, but does the following look like something worth committing? %%% diff -r ea818a53fb86 share/man/man4/snd_hda.4 --- a/share/man/man4/snd_hda.4 Thu Nov 06 07:04:46 2008 +0200 +++ b/share/man/man4/snd_hda.4 Thu Nov 06 18:09:06 2008 +0200 @@ -57,8 +57,8 @@ driver that allows the generic audio driver, .Xr sound 4 , to be used with this hardware. -.Nm -only supports audio functions. +Only audio functions are supported by +.Nm . Modem, HDMI and other possible functions are not implemented. .Pp The @@ -68,7 +68,7 @@ Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio devices. .Pp -According to HDA and UAA specifications, depending on number of HDA buses +According to HDA and UAA specifications, depending on the number of HDA buses and codecs present in system, their audio capabilities and BIOS provided configuration, the .Nm @@ -76,14 +76,16 @@ For example, one device for main rear 7.1 output and inputs, one device for independent headset connectors at front and one device for SPDIF or HDMI audio input/output. -Usually that assignment may be widely tuned by using device hints. -A lot of useful information about driver operation and present audio setup may -be obtained from the driver verbose boot messages. +The assignment of audio inputs and outputs may be tuned with +.Xr device.hints 5 . +The driver's verbose boot messages provide a lot of information about +the operation of the driver and present audio setup. .Pp -You can select audio device to use by default with hw.snd.default_unit -sysctl described in -.Xr sound 4 -or explicitly specify it in appliation settings. +The default audio device may be tuned by setting the +.Ar hw.snd.default_unit +sysctl, as described in +.Xr sound 4 , +or by explicitly specify it in application settings. .Ss Boot-time Configuration The following variables are available at boot-time through the .Xr device.hints 5 @@ -123,18 +125,26 @@ .Dq Li nofixedrate , will do the opposite and takes precedence. Options can be separated by whitespace and commas. -GPIO is a codecs General Purpose I/O pins which system integrators sometimes +.Dq Li GPIO Ns s +are a codec's General Purpose I/O pins, which system integrators sometimes use to control external muters, amplifiers and so on. -If you have no sound or sound volume is not adequate you may need to find a -GPIO combination required for your system. -ivrefX/ovrefX options controls voltage used to power external microphones -and so on. +If you have no sound, or sound volume is not adequate, you may have to +experiment a bit with the GPIO setup to find the optimal setup for your +system. +The +.Dq Li ivref Ns Ar X +and +.Dq Li ovref Ns Ar X +options control the voltage used to power external microphones. .It Va hint.hdac.%d.msi Controls MSI (Message Signaled Interrupts) support. .It Va hint.hdac.%d.cad%d.nid%d.config Overrides codec pin configuration set by BIOS. -May be specified as a 32bit HEX value with a leading "0x" or as a set of -space separated "option=value" pairs. +May be specified as a 32-bit hexadecimal value with a leading +.Dq 0x , +or as a set of space-separated +.Dq Ar option Ns = Ns Ar value +pairs. .El .Pp Pin configuration is the UAA driver's main source of information about codec @@ -143,33 +153,36 @@ by system integrators for specific system requirements. The .Nm -driver allows users to override it to fix integrator mistakes or to use codec -in alternative ways, for example, to get stereo output and 2 inputs -instead of a single 5.1 output. -Configuration includes the following options: +driver allows users to override it to fix integrator mistakes or to use the available codecs +in alternative ways (for example to get stereo output and 2 inputs +instead of a single 5.1 output). +.Pp +The following options are supported: .Bl -tag -width ".Va device=" -offset indent .It Va as Association number. -Associations are used to group individual pins to form a complex multipin +Associations are used to group individual pins to form a complex multi-pin device. -For example, to group 4 connectors for 7.1 output or to treat several +For example, to group 4 connectors for 7.1 output, or to treat several input connectors as sources for the same input device. -Can be specified as number from 0 to 15. -Association number 0 means disabled pin, number 15 is a set of independent -unassociated pins. -Each association includes only pins of the same direction (in/out) and -detected atomically - all pins or none. -For every pair of input+output associations in order of their numeration -separate PCM audio device is created. +Association numbers can be specified as numeric values from 0 to 15. +A value of 0 means disabled pin. +A value of 15 is a set of independent unassociated pins. +Each association includes only pins of the same direction (in/out) and is +detected atomically (all pins or none). +A separate PCM audio device is created for every pair of input and +output associations. .It Va seq Sequence number. -This unique inside every association number used to order pins inside -association. -Can be specified as a number from 0 to 15. -Sequence number 15 for output associations has also special meaning. -Output pin with sequence number 15 and device type Headhones will duplicate -(with automatic mute if jack detection is supported) the first pin in that -association. +A unique, per-association number used to order pins inside the +particular association. +Sequence numbers can be specified as numeric values from 0 to 15. +.Pp +The sequence number 15 has a special meaning for output associations. +Output pins with this number and device type +.Dq Ar Headphones +will duplicate (with automatic mute if jack detection is supported) the +first pin in that association. .It Va device Device type. Can be specified as a number from 0 to 15 or as a name: @@ -193,27 +206,31 @@ The device type also describes the pin direction (in/out). For example, .Dq Li CD -always means input pin, while +always means an input pin, while .Dq Li Headphones -always means output. +always means an output pin. .It Va conn Connection type. -Can be specified as a number from 0 to 3 or as a name: +Can be specified as a number from 0 to 3. +The connection type can also be specified as one of the special names .Dq Li Jack , .Dq Li None , .Dq Li Fixed , or .Dq Li Both . -Pins with +Pins with a connection type of .Dq Li None -connection type are disabled. +are disabled. .It Va ctype Connector physical type. Can be specified as a number from 0 to 15. -This is a reference only value which is ignored by the driver. +This is a reference only value. +It is ignored by the +.Nm +driver. .It Va color Connector color. -Can be specified as a number from 0 to 15 or as a name: +Can be specified as a number from 0 to 15 or as one of the names .Dq Li Unknown , .Dq Li Black , .Dq Li Grey , @@ -231,16 +248,23 @@ .Dq Li White , or .Dq Li Other . -This is a reference only value which is ignored by the driver. +This is a reference only value . +It is ignored by the +.Nm +driver. .It Va loc Connector physical location. Can be specified as a number from 0 to 63. -This is a reference only value which is ignored by the driver. +This is a reference only value. +It is ignored by the +.Nm +driver. .It Va misc Misc bits. Can be specified as a number from 0 to 15. -Bit 0, if set, tells that jack detection on this pin supported by the codec -is not implemented in hardware. +.Pp +Bit 0 has a special meaning. When set it means that jack detection is +not implemented in hardware. .El .Ss Runtime Configuration The following @@ -250,8 +274,9 @@ devices: .Bl -tag -width ".Va dev.hdac.%d.polling" -offset indent .It Va dev.hdac.%d.polling -Enables polling mode, where the driver operates by querying the device -state on timer ticks using +Enables polling mode. +In this mode the driver operates by querying the device state on timer +ticks using .Xr callout 9 instead of interrupts. Polling is disabled by default. @@ -264,14 +289,17 @@ capabilities and jack sense status to console and syslog. .El .Sh EXAMPLES -Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example. It has two +Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example. +This system has two audio connectors on a front side, three audio connectors on a rear side and one -internal speaker. According to verbose driver output and codec datasheet, -codec has five stereo DACs and two stereo ADCs, all of them are routable to -any codec pin (external connector). All codec pins are reversible. +internal speaker. +According to verbose driver output and the codec datasheet, +this codec has five stereo DACs and two stereo ADCs, all of them are routable to +any codec pin (external connector). +All codec pins are reversible. .Pp So high codec uniformity and flexibility allow driver to configure it in many -deferent ways, depending on requested pins usage decribed by pins configuration. +different ways, depending on requested pins usage decribed by pins configuration. Driver reports such default pin configuration when verbose messages enabled: .Bd -literal hdac0: nid 20 0x01014020 as 2 seq 0 Line-out Jack jack 1 loc 1 color Green misc 0 @@ -308,49 +336,83 @@ hdac0: Pin nid=25 seq=15 .Ed .Pp -Each pcm device uses two associations: one for playback and one for recording. -Associations processed and assigned to pcm devices in order of their numbers. -It means that association #0 (1) will become pcm0 device playback, using -internal speaker and headphones jack with speaker automute on headphones -connection. -Association #1 (2) will become pcm1 playback, using the Line-out jack. -Association #2 (3) will become pcm0 recording, using external microphones and -line-in jack. +Each +.Xr pcm 4 +device uses two associations: one for playback and one for recording. +Associations processed and assigned to +.Xr pcm 4 +devices in increasing numerical order. +In this case association #0 (1) will become +.Li pcm0 +device playback, using the internal speakers and headphones jack with +speaker automute of the headphones. +Association #1 (2) will become +.Li pcm1 +playback, using the +.Ar Line-out +jack. +Association #2 (3) will become +.Li pcm0 +recording, using the external microphones and the line-in jack. .Pp -Driver provides extensive set of verbose messages to diagnose it's operation -logic and description of resulted codec configuration. +The +.Nm +driver provides extensive verbose messages to diagnose its operation +logic and describe its current codec configuration. .Pp -Using device.hints it is possible to modify existing pins configuration to -create broad range of different audio setups. Here is examples of some setups -possible for the described hardware: +Using +.Xr device.hints 5 +it is possible to modify the configuration of the existing pins, +allowing a broad range of different audio setups. +Here are a few examples of some setups possible for this particular +hardware: .Ss Example 1 -Setting +Setting the +.Xr device.hints 5 +options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1" hint.hdac.0.cad0.nid21.config="as=2" .Ed .Pp -will swap line-out and speaker functions. So pcm0 device will play to the -line-out and headphones jacks with line-out automute on headphones connection. -Recording on pcm0 will go from two external microphones and line-in jacks. -pcm1 playback will go to the internal speaker. +will swap line-out and speaker functions. +So the +.Li pcm0 +device will play to the line-out and headphones jacks, and line-out will +automute the headphones connection. +Recording on +.Li pcm0 +will go from two external microphones and line-in jacks. +.Li pcm1 +playback will go to the internal speaker. .Pp .Ss Example 2 -Setting +Setting the +.Xr device.hints 5 +options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones" hint.hdac.0.cad0.nid27.config="as=2 seq=0" hint.hdac.0.cad0.nid25.config="as=4 seq=0" .Ed .Pp -will split headphones and one of mics to separate device. So pcm0 device will -play to the internal speaker and line-out jack with speaker automute on -line-out connection. Recording on pcm0 will go from one external microphone -and line-in jacks. pcm1 will be completely dedicated to headset (headphones and -mic) connected to the front connectors. +will split the headphones and one of the microphones to a separate device. +The +.Li pcm0 +device will play to the internal speaker and to the line-out jack, with +speaker automute on the line-out connection. +Recording on +.Li pcm0 +will use input from one external microphone and the line-in jacks. +The +.Li pcm1 +device will be completely dedicated to a headset (headphones and mic) +connected to the front connectors. .Pp .Ss Example 3 -Setting +Setting the +.Xr device.hints 5 +options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1 seq=0" hint.hdac.0.cad0.nid26.config="as=2 seq=0" @@ -360,12 +422,21 @@ hint.hdac.0.cad0.nid21.config="as=6 seq=0" .Ed .Pp -will give 4 independent devices: pcm0 - line-out + line-in, pcm1 - headphones -+ mic, pcm2 - additional line-out via retasked rear mic jack, pcm3 - internal -speaker. +will give 4 independent devices: +.Li pcm0 +.Pq line-out and line-in , +.Li pcm1 +.Pq headphones and mic , +.Li pcm2 +.Pq additional line-out via retasked rear mic jack , +and +.Li pcm3 +.Pq internal speaker . .Pp .Ss Example 4 -Setting +Setting the +.Xr device.hints 5 +options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1 seq=0" hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out" @@ -373,10 +444,13 @@ hint.hdac.0.cad0.nid21.config="as=2 seq=0" .Ed .Pp -will give 2 devices: pcm0 - 5.1 playback via 3 rear (line-out and retasked -mic and line-in) connectors and front headphones with rear connectors automute -on headphones connection + front mic recording. pcm1 - internal speaker -playback. +will give 2 devices: +.Li pcm0 +for 5.1 playback via 3 rear connectors and front headphones (line-out, +retasked mic and line-in), with rear connectors automute on headphones +connection and front mic recording, and +.Li pcm1 +for internal speaker playback. .Sh HARDWARE The .Nm @@ -533,4 +607,4 @@ driver seems to attach and work, but without any sound. .Pp Due to OSS limitation multichannel (not multidevice) playback is not -supported. \ No newline at end of file +supported. %%%
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?87r65okf7n.fsf>