summaryrefslogtreecommitdiff
path: root/Documentation/DocBook/via-audio.tmpl
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/via-audio.tmpl')
-rw-r--r--Documentation/DocBook/via-audio.tmpl597
1 files changed, 597 insertions, 0 deletions
diff --git a/Documentation/DocBook/via-audio.tmpl b/Documentation/DocBook/via-audio.tmpl
new file mode 100644
index 000000000000..36e642147d6b
--- /dev/null
+++ b/Documentation/DocBook/via-audio.tmpl
@@ -0,0 +1,597 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
+
+<book id="ViaAudioGuide">
+ <bookinfo>
+ <title>Via 686 Audio Driver for Linux</title>
+
+ <authorgroup>
+ <author>
+ <firstname>Jeff</firstname>
+ <surname>Garzik</surname>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>1999-2001</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 "super southbridge" chips contain
+ AC97-compatible audio logic which features dual 16-bit stereo
+ PCM sound channels (full duplex), 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 and recording, but hardware-assisted
+ FM features, and hardware buffer direct-access (mmap)
+ support are not yet available.
+ </para>
+ <para>
+ This driver supports any Linux kernel version after 2.4.10.
+ </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://sf.net/projects/gkernel/ 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>Low volume</term>
+ <listitem>
+ <para>
+ Volume too low on many systems. Workaround: use mixer program
+ such as xmixer to increase volume.
+ </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>
+ <para>
+ Rui Sousa <email>rui.sousa@conexant.com</email>, for bugfixing
+ MMAP support, and several other notable fixes that resulted from
+ his hard work and testing.
+ </para>
+ <para>
+ Adrian Cox <email>adrian@humboldt.co.uk</email>, for bugfixing
+ MMAP support, and several other notable fixes that resulted from
+ his hard work and testing.
+ </para>
+ <para>
+ Thomas Sailer for further bugfixes.
+ </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 CONFIG_SOUND_VIA82CXXX_PROCFS,
+ and remove the /proc support code. 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>
+ GNU indent formatting options:
+ <programlisting>
+-kr -i8 -ts8 -br -ce -bap -sob -l80 -pcs -cs -ss -bs -di1 -nbc -lp -psl
+ </programlisting>
+ </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="version191"><title>
+Version 1.9.1
+</title>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ DSP read/write bugfixes from Thomas Sailer.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Add new PCI id for single-channel use of Via 8233.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Other bug fixes, tweaks, new ioctls.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</sect1>
+
+<sect1 id="version1115"><title>
+Version 1.1.15
+</title>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ Support for variable fragment size and variable fragment number (Rui
+ Sousa)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Fixes for the SPEED, STEREO, CHANNELS, FMT ioctls when in read &amp;
+ write mode (Rui Sousa)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Mmaped sound is now fully functional. (Rui Sousa)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Make sure to enable PCI device before reading any of its PCI
+ config information. (fixes potential hotplug problems)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Clean up code a bit and add more internal function documentation.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ AC97 codec access fixes (Adrian Cox)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Big endian fixes (Adrian Cox)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ MIDI support (Adrian Cox)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Detect and report locked-rate AC97 codecs. If your hardware only
+ supports 48Khz (locked rate), then your recording/playback software
+ must upsample or downsample accordingly. The hardware cannot do it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use new pci_request_regions and pci_disable_device functions in
+ kernel 2.4.6.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</sect1>
+
+<sect1 id="version1114"><title>
+Version 1.1.14
+</title>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ Use VM_RESERVE when available, to eliminate unnecessary page faults.
+ </para>
+ </listitem>
+ </itemizedlist>
+</sect1>
+
+<sect1 id="version1112"><title>
+Version 1.1.12
+</title>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ mmap bug fixes from Linus.
+ </para>
+ </listitem>
+ </itemizedlist>
+</sect1>
+
+<sect1 id="version1111"><title>
+Version 1.1.11
+</title>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ Many more bug fixes. mmap enabled by default, but may still be buggy.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Uses new and spiffy method of mmap'ing the DMA buffer, based
+ on a suggestion from Linus.
+ </para>
+ </listitem>
+ </itemizedlist>
+</sect1>
+
+<sect1 id="version1110"><title>
+Version 1.1.10
+</title>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ Many bug fixes. mmap enabled by default, but may still be buggy.
+ </para>
+ </listitem>
+ </itemizedlist>
+</sect1>
+
+<sect1 id="version119"><title>
+Version 1.1.9
+</title>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ Redesign and rewrite audio playback implementation. (faster and smaller, hopefully)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Implement recording and full duplex (DSP_CAP_DUPLEX) support.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Make procfs support optional.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Quick interrupt status check, to lessen overhead in interrupt
+ sharing situations.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Add mmap(2) support. Disabled for now, it is still buggy and experimental.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Surround all syscalls with a semaphore for cheap and easy SMP protection.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Fix bug in channel shutdown (hardware channel reset) code.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Remove unnecessary spinlocks (better performance).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Eliminate "unknown AFMT" message by using a different method
+ of selecting the best AFMT_xxx sound sample format for use.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Support for realtime hardware pointer position reporting
+ (DSP_CAP_REALTIME, SNDCTL_DSP_GETxPTR ioctls)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Support for capture/playback triggering
+ (DSP_CAP_TRIGGER, SNDCTL_DSP_SETTRIGGER ioctls)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ SNDCTL_DSP_SETDUPLEX and SNDCTL_DSP_POST ioctls now handled.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Rewrite open(2) and close(2) logic to allow only one user at
+ a time. All other open(2) attempts will sleep until they succeed.
+ FIXME: open(O_RDONLY) and open(O_WRONLY) should be allowed to succeed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Reviewed code to ensure that SMP and multiple audio devices
+ are fully supported.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</sect1>
+
+<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/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>
+!Isound/oss/via82cxxx_audio.c
+ </chapter>
+
+</book>
+
+