patch-2.4.0-test2 linux/Documentation/DocBook/via-audio.tmpl

Next file: linux/Documentation/arm/README
Previous file: linux/Documentation/DocBook/mousedrivers.tmpl
Back to the patch index
Back to the overall index

diff -u --recursive --new-file v2.4.0-test1/linux/Documentation/DocBook/via-audio.tmpl linux/Documentation/DocBook/via-audio.tmpl
@@ -0,0 +1,383 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
+
+<book id="ViaAudioGuide">
+ <bookinfo>
+  <title>Via 686 Audio Driver for Linux</title>
+  
+  <authorgroup>
+   <author>
+    <firstname>Jeff</firstname>
+    <surname>Garzik</surname>
+    <affiliation>
+     <address>
+      <email>jgarzik@mandrakesoft.com</email>
+     </address>
+    </affiliation>
+   </author>
+  </authorgroup>
+
+  <copyright>
+   <year>2000</year>
+   <holder>Jeff Garzik</holder>
+  </copyright>
+
+  <legalnotice>
+   <para>
+     This documentation is free software; you can redistribute
+     it and/or modify it under the terms of the GNU General Public
+     License as published by the Free Software Foundation; either
+     version 2 of the License, or (at your option) any later
+     version.
+   </para>
+      
+   <para>
+     This program is distributed in the hope that it will be
+     useful, but WITHOUT ANY WARRANTY; without even the implied
+     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+     See the GNU General Public License for more details.
+   </para>
+      
+   <para>
+     You should have received a copy of the GNU General Public
+     License along with this program; if not, write to the Free
+     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+     MA 02111-1307 USA
+   </para>
+      
+   <para>
+     For more details see the file COPYING in the source
+     distribution of Linux.
+   </para>
+  </legalnotice>
+ </bookinfo>
+
+<toc></toc>
+
+  <chapter id="intro">
+      <title>Introduction</title>
+  <para>
+  	The Via VT82C686A and VT82C686A "super southbridge" chips contain
+	AC97-compatible audio logic which features dual full-duplex 16-bit stereo
+	PCM sound channels, plus a third PCM channel intended for use
+	in hardware-assisted FM synthesis.
+  </para>
+  <para>
+  	The current Linux kernel audio driver for this family of chips
+	supports audio playback, but recording and hardware-assisted
+	FM support features are not yet available.
+  </para>
+  <para>
+  	This driver supports any Linux kernel version after 2.3.50.
+  </para>
+  <para>
+	Please send bug reports to the mailing list <email>linux-via@gtf.org</email>.
+	To subscribe, e-mail <email>majordomo@gtf.org</email> with
+  </para>
+  <programlisting>
+	subscribe linux-via
+  </programlisting>
+  <para>
+	in the body of the message.
+  </para>
+  </chapter>
+  
+  <chapter id="install">
+      <title>Driver Installation</title>
+  <para>
+  	To use this audio driver, select the
+	CONFIG_SOUND_VIA82CXXX option in the section Sound during kernel configuration.
+	Follow the usual kernel procedures for rebuilding the kernel,
+	or building and installing driver modules.
+  </para>
+  <para>
+  	To make this driver the default audio driver, you can add the
+	following to your /etc/conf.modules file:
+  </para>
+  <programlisting>
+	alias sound via82cxxx_audio
+  </programlisting>
+  <para>
+  	Note that soundcore and ac97_codec support modules
+	are also required for working audio, in addition to
+	the via82cxxx_audio module itself.
+  </para>
+  </chapter>
+  
+  <chapter id="reportbug">
+      <title>Submitting a bug report</title>
+  <sect1 id="bugrepdesc"><title>Description of problem</title>
+  <para>
+	Describe the application you were using to play/record sound, and how
+	to reproduce the problem.
+  </para>
+  </sect1>
+  <sect1 id="bugrepdiag"><title>Diagnostic output</title>
+  <para>
+	Obtain the via-audio-diag diagnostics program from
+	http://gtf.org/garzik/drivers/via82cxxx/ and provide a dump of the
+	audio chip's registers while the problem is occurring.  Sample command line:
+  </para>
+  <programlisting>
+	./via-audio-diag -aps > diag-output.txt
+  </programlisting>
+  </sect1>
+  <sect1 id="bugrepdebug"><title>Driver debug output</title>
+  <para>
+	Define <constant>VIA_DEBUG</constant> at the beginning of the driver, then capture and email
+	the kernel log output.  This can be viewed in the system kernel log (if
+	enabled), or via the dmesg program.  Sample command line:
+  </para>
+  <programlisting>
+	dmesg > /tmp/dmesg-output.txt
+  </programlisting>
+  </sect1>
+  <sect1 id="bugrepprintk"><title>Bigger kernel message buffer</title>
+  <para>
+	If you wish to increase the size of the buffer displayed by dmesg, then
+	change the <constant>LOG_BUF_LEN</constant> macro at the top of linux/kernel/printk.c, recompile
+	your kernel, and pass the <constant>LOG_BUF_LEN</constant> value to dmesg.  Sample command line with
+	<constant>LOG_BUF_LEN</constant> == 32768:
+  </para>
+  <programlisting>
+	dmesg -s 32768 > /tmp/dmesg-output.txt
+  </programlisting>
+  </sect1>
+  </chapter>
+  
+  <chapter id="bugs">
+     <title>Known Bugs And Assumptions</title>
+  <para>
+  <variablelist>
+    <varlistentry><term>Recording support</term>
+    <listitem>
+    <para>
+    	Recording support is currently missing.
+    </para>
+    </listitem></varlistentry>
+
+    <varlistentry><term>MMAP support</term>
+    <listitem>
+    <para>
+    	MMAP support is currently missing.  Make sure to
+	test with Quake.
+    </para>
+    </listitem></varlistentry>
+
+    <varlistentry><term>AC97 codec timeout during init</term>
+    <listitem>
+    <para>
+    	A warning message "via82cxxx: timeout while reading AC97
+	codec" is printed during driver initialization.  This
+	message can safely be ignored.
+    </para>
+    </listitem></varlistentry>
+
+    <varlistentry><term>Low volume</term>
+    <listitem>
+    <para>
+	Volume too low on many systems.  Workaround:  use mixer program
+	such as xmixer to increase volume.
+    </para>
+    </listitem></varlistentry>
+
+    <varlistentry><term>RealPlayer trouble</term>
+    <listitem>
+    <para>
+	RealPlayer output very scratchy.  Workaround:  use esd, and
+	configure RealPlayer to output to esd.
+    </para>
+    </listitem></varlistentry>
+
+    <varlistentry><term>Broken apps</term>
+    <listitem>
+    <para>
+	Applications which attempt to open the sound device in read/write
+	mode (O_RDWR) will fail.  This is incorrect OSS behavior, but since
+	this driver will eventually support recording as well as playback,
+	we will be able to (in the future) support even broken programs which
+	unconditionally use O_RDWR.
+    </para>
+    </listitem></varlistentry>
+
+  </variablelist>
+	
+  </para>
+  </chapter>
+
+  <chapter id="thanks">
+      <title>Thanks</title>
+  <para>
+	Via for providing e-mail support, specs, and NDA'd source code.
+  </para>
+  <para>
+	MandrakeSoft for providing hacking time.
+  </para>
+  <para>
+	AC97 mixer interface fixes and debugging by Ron Cemer <email>roncemer@gte.net</email>.
+  </para>
+  </chapter>
+  
+  <chapter id="notes">
+     <title>Random Notes</title>
+  <para>
+	Two /proc pseudo-files provide diagnostic information.  This is generally
+	not useful to most users.  Power users can disable VIA_PROC_FS macro in the 
+	driver source code, and remove the /proc support code.  In any case, once
+	version 2.0.0 is released, the /proc support code will be disabled by
+	default.  Available /proc pseudo-files:
+  </para>
+  <programlisting>
+	/proc/driver/via/0/info
+	/proc/driver/via/0/ac97
+  </programlisting>
+  <para>
+	This driver by default supports all PCI audio devices which report
+	a vendor id of 0x1106, and a device id of 0x3058.  Subsystem vendor
+	and device ids are not examined.
+  </para>
+  <para>
+	Only supports a single sound chip, as this is a motherboard chipset.
+	Some architecture remains for multiple cards, feel free to submit
+	a patch to clean some of that up.
+  </para>
+  <para>
+	No consideration for SMP, this chipset is not known to be found on
+	any SMP motherboards.  However, spin_locks must be used anyway in order
+	to handle interrupts correctly.
+  </para>
+  <para>
+	GNU indent formatting options:  -kr -i8 -pcs
+  </para>
+  <para>
+	Via has graciously donated e-mail support and source code to help further
+	the development of this driver.  Their assistance has been invaluable
+	in the design and coding of the next major version of this driver.
+  </para>
+  <para>
+	The Via audio chip apparently provides a second PCM scatter-gather
+	DMA channel just for FM data, but does not have a full hardware MIDI
+	processor.  I haven't put much thought towards a solution here, but it
+	might involve using SoftOSS midi wave table, or simply disabling MIDI
+	support altogether and using the FM PCM channel as a second (input? output?)
+  </para>
+  </chapter>
+
+  <chapter id="changelog">
+      <title>Driver ChangeLog</title>
+
+<sect1 id="version118"><title>
+Version 1.1.8
+</title>
+  <itemizedlist spacing=compact>
+   <listitem>
+    <para>
+    	Clean up interrupt handler output.  Fixes the following kernel error message:
+    </para>
+  	<programlisting>
+	unhandled interrupt ...
+  	</programlisting>
+   </listitem>
+
+   <listitem>
+    <para>
+    	Convert documentation to DocBook, so that PDF, HTML and PostScript (.ps) output is readily
+	available.
+    </para>
+   </listitem>
+
+  </itemizedlist>
+</sect1>
+
+<sect1 id="version117"><title>
+Version 1.1.7
+</title>
+  <itemizedlist spacing=compact>
+   <listitem>
+    <para>
+ Fix module unload bug where mixer device left registered
+  after driver exit
+    </para>
+   </listitem>
+  </itemizedlist>
+</sect1>
+
+<sect1 id="version116"><title>
+Version 1.1.6
+</title>
+  <itemizedlist spacing=compact>
+   <listitem>
+    <para>
+ Rewrite via_set_rate to mimic ALSA basic AC97 rate setting
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+ Remove much dead code
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+ Complete spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+ Fix build problem in via_dsp_ioctl
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+ Optimize included headers to eliminate headers found in linux/drivers/sound
+	</para>
+   </listitem>
+  </itemizedlist>
+</sect1>
+
+<sect1 id="version115"><title>
+Version 1.1.5
+</title>
+  <itemizedlist spacing=compact>
+   <listitem>
+    <para>
+ Disable some overly-verbose debugging code
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+ Remove unnecessary sound locks
+   </para>
+   </listitem>
+   <listitem>
+    <para>
+ Fix some ioctls for better time resolution
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+ Begin spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl
+    </para>
+   </listitem>
+  </itemizedlist>
+</sect1>
+
+<sect1 id="version114"><title>
+Version 1.1.4
+</title>
+  <itemizedlist spacing=compact>
+   <listitem>
+    <para>
+ Completed rewrite of driver.  Eliminated SoundBlaster compatibility
+  completely, and now uses the much-faster scatter-gather DMA engine.
+    </para>
+   </listitem>
+  </itemizedlist>
+</sect1>
+
+  </chapter>
+  
+  <chapter id="intfunctions">
+     <title>Internal Functions</title>
+!Idrivers/sound/via82cxxx_audio.c
+  </chapter>
+
+</book>
FUNET's LINUX-ADM group, linux-adm@nic.funet.fi
TCL-scripts by Sam Shen (who was at: slshen@lbl.gov)