diff options
Diffstat (limited to 'Documentation/DocBook/via-audio.tmpl')
| -rw-r--r-- | Documentation/DocBook/via-audio.tmpl | 597 |
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 & + 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> + + |