1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
5 <book id="ViaAudioGuide">
7 <title>Via 686 Audio Driver for Linux</title>
11 <firstname>Jeff</firstname>
12 <surname>Garzik</surname>
17 <year>1999-2001</year>
18 <holder>Jeff Garzik</holder>
23 This documentation is free software; you can redistribute
24 it and/or modify it under the terms of the GNU General Public
25 License as published by the Free Software Foundation; either
26 version 2 of the License, or (at your option) any later
31 This program is distributed in the hope that it will be
32 useful, but WITHOUT ANY WARRANTY; without even the implied
33 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
34 See the GNU General Public License for more details.
38 You should have received a copy of the GNU General Public
39 License along with this program; if not, write to the Free
40 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
45 For more details see the file COPYING in the source
46 distribution of Linux.
54 <title>Introduction</title>
56 The Via VT82C686A "super southbridge" chips contain
57 AC97-compatible audio logic which features dual 16-bit stereo
58 PCM sound channels (full duplex), plus a third PCM channel intended for use
59 in hardware-assisted FM synthesis.
62 The current Linux kernel audio driver for this family of chips
63 supports audio playback and recording, but hardware-assisted
64 FM features, and hardware buffer direct-access (mmap)
65 support are not yet available.
68 This driver supports any Linux kernel version after 2.4.10.
71 Please send bug reports to the mailing list <email>linux-via@gtf.org</email>.
72 To subscribe, e-mail <email>majordomo@gtf.org</email> with
78 in the body of the message.
82 <chapter id="install">
83 <title>Driver Installation</title>
85 To use this audio driver, select the
86 CONFIG_SOUND_VIA82CXXX option in the section Sound during kernel configuration.
87 Follow the usual kernel procedures for rebuilding the kernel,
88 or building and installing driver modules.
91 To make this driver the default audio driver, you can add the
92 following to your /etc/conf.modules file:
95 alias sound via82cxxx_audio
98 Note that soundcore and ac97_codec support modules
99 are also required for working audio, in addition to
100 the via82cxxx_audio module itself.
104 <chapter id="reportbug">
105 <title>Submitting a bug report</title>
106 <sect1 id="bugrepdesc"><title>Description of problem</title>
108 Describe the application you were using to play/record sound, and how
109 to reproduce the problem.
112 <sect1 id="bugrepdiag"><title>Diagnostic output</title>
114 Obtain the via-audio-diag diagnostics program from
115 http://sf.net/projects/gkernel/ and provide a dump of the
116 audio chip's registers while the problem is occurring. Sample command line:
119 ./via-audio-diag -aps > diag-output.txt
122 <sect1 id="bugrepdebug"><title>Driver debug output</title>
124 Define <constant>VIA_DEBUG</constant> at the beginning of the driver, then capture and email
125 the kernel log output. This can be viewed in the system kernel log (if
126 enabled), or via the dmesg program. Sample command line:
129 dmesg > /tmp/dmesg-output.txt
132 <sect1 id="bugrepprintk"><title>Bigger kernel message buffer</title>
134 If you wish to increase the size of the buffer displayed by dmesg, then
135 change the <constant>LOG_BUF_LEN</constant> macro at the top of linux/kernel/printk.c, recompile
136 your kernel, and pass the <constant>LOG_BUF_LEN</constant> value to dmesg. Sample command line with
137 <constant>LOG_BUF_LEN</constant> == 32768:
140 dmesg -s 32768 > /tmp/dmesg-output.txt
146 <title>Known Bugs And Assumptions</title>
149 <varlistentry><term>Low volume</term>
152 Volume too low on many systems. Workaround: use mixer program
153 such as xmixer to increase volume.
155 </listitem></varlistentry>
162 <chapter id="thanks">
163 <title>Thanks</title>
165 Via for providing e-mail support, specs, and NDA'd source code.
168 MandrakeSoft for providing hacking time.
171 AC97 mixer interface fixes and debugging by Ron Cemer <email>roncemer@gte.net</email>.
174 Rui Sousa <email>rui.sousa@conexant.com</email>, for bugfixing
175 MMAP support, and several other notable fixes that resulted from
176 his hard work and testing.
179 Adrian Cox <email>adrian@humboldt.co.uk</email>, for bugfixing
180 MMAP support, and several other notable fixes that resulted from
181 his hard work and testing.
184 Thomas Sailer for further bugfixes.
189 <title>Random Notes</title>
191 Two /proc pseudo-files provide diagnostic information. This is generally
192 not useful to most users. Power users can disable CONFIG_SOUND_VIA82CXXX_PROCFS,
193 and remove the /proc support code. Once
194 version 2.0.0 is released, the /proc support code will be disabled by
195 default. Available /proc pseudo-files:
198 /proc/driver/via/0/info
199 /proc/driver/via/0/ac97
202 This driver by default supports all PCI audio devices which report
203 a vendor id of 0x1106, and a device id of 0x3058. Subsystem vendor
204 and device ids are not examined.
207 GNU indent formatting options:
209 -kr -i8 -ts8 -br -ce -bap -sob -l80 -pcs -cs -ss -bs -di1 -nbc -lp -psl
213 Via has graciously donated e-mail support and source code to help further
214 the development of this driver. Their assistance has been invaluable
215 in the design and coding of the next major version of this driver.
218 The Via audio chip apparently provides a second PCM scatter-gather
219 DMA channel just for FM data, but does not have a full hardware MIDI
220 processor. I haven't put much thought towards a solution here, but it
221 might involve using SoftOSS midi wave table, or simply disabling MIDI
222 support altogether and using the FM PCM channel as a second (input? output?)
226 <chapter id="changelog">
227 <title>Driver ChangeLog</title>
229 <sect1 id="version191"><title>
232 <itemizedlist spacing="compact">
235 DSP read/write bugfixes from Thomas Sailer.
241 Add new PCI id for single-channel use of Via 8233.
247 Other bug fixes, tweaks, new ioctls.
254 <sect1 id="version1115"><title>
257 <itemizedlist spacing="compact">
260 Support for variable fragment size and variable fragment number (Rui
267 Fixes for the SPEED, STEREO, CHANNELS, FMT ioctls when in read &
268 write mode (Rui Sousa)
274 Mmaped sound is now fully functional. (Rui Sousa)
280 Make sure to enable PCI device before reading any of its PCI
281 config information. (fixes potential hotplug problems)
287 Clean up code a bit and add more internal function documentation.
293 AC97 codec access fixes (Adrian Cox)
299 Big endian fixes (Adrian Cox)
305 MIDI support (Adrian Cox)
311 Detect and report locked-rate AC97 codecs. If your hardware only
312 supports 48Khz (locked rate), then your recording/playback software
313 must upsample or downsample accordingly. The hardware cannot do it.
319 Use new pci_request_regions and pci_disable_device functions in
327 <sect1 id="version1114"><title>
330 <itemizedlist spacing="compact">
333 Use VM_RESERVE when available, to eliminate unnecessary page faults.
339 <sect1 id="version1112"><title>
342 <itemizedlist spacing="compact">
345 mmap bug fixes from Linus.
351 <sect1 id="version1111"><title>
354 <itemizedlist spacing="compact">
357 Many more bug fixes. mmap enabled by default, but may still be buggy.
363 Uses new and spiffy method of mmap'ing the DMA buffer, based
364 on a suggestion from Linus.
370 <sect1 id="version1110"><title>
373 <itemizedlist spacing="compact">
376 Many bug fixes. mmap enabled by default, but may still be buggy.
382 <sect1 id="version119"><title>
385 <itemizedlist spacing="compact">
388 Redesign and rewrite audio playback implementation. (faster and smaller, hopefully)
394 Implement recording and full duplex (DSP_CAP_DUPLEX) support.
400 Make procfs support optional.
406 Quick interrupt status check, to lessen overhead in interrupt
413 Add mmap(2) support. Disabled for now, it is still buggy and experimental.
419 Surround all syscalls with a semaphore for cheap and easy SMP protection.
425 Fix bug in channel shutdown (hardware channel reset) code.
431 Remove unnecessary spinlocks (better performance).
437 Eliminate "unknown AFMT" message by using a different method
438 of selecting the best AFMT_xxx sound sample format for use.
444 Support for realtime hardware pointer position reporting
445 (DSP_CAP_REALTIME, SNDCTL_DSP_GETxPTR ioctls)
451 Support for capture/playback triggering
452 (DSP_CAP_TRIGGER, SNDCTL_DSP_SETTRIGGER ioctls)
458 SNDCTL_DSP_SETDUPLEX and SNDCTL_DSP_POST ioctls now handled.
464 Rewrite open(2) and close(2) logic to allow only one user at
465 a time. All other open(2) attempts will sleep until they succeed.
466 FIXME: open(O_RDONLY) and open(O_WRONLY) should be allowed to succeed.
472 Reviewed code to ensure that SMP and multiple audio devices
480 <sect1 id="version118"><title>
483 <itemizedlist spacing="compact">
486 Clean up interrupt handler output. Fixes the following kernel error message:
489 unhandled interrupt ...
495 Convert documentation to DocBook, so that PDF, HTML and PostScript (.ps) output is readily
503 <sect1 id="version117"><title>
506 <itemizedlist spacing="compact">
509 Fix module unload bug where mixer device left registered
516 <sect1 id="version116"><title>
519 <itemizedlist spacing="compact">
522 Rewrite via_set_rate to mimic ALSA basic AC97 rate setting
527 Remove much dead code
532 Complete spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl
537 Fix build problem in via_dsp_ioctl
542 Optimize included headers to eliminate headers found in linux/sound
548 <sect1 id="version115"><title>
551 <itemizedlist spacing="compact">
554 Disable some overly-verbose debugging code
559 Remove unnecessary sound locks
564 Fix some ioctls for better time resolution
569 Begin spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl
575 <sect1 id="version114"><title>
578 <itemizedlist spacing="compact">
581 Completed rewrite of driver. Eliminated SoundBlaster compatibility
582 completely, and now uses the much-faster scatter-gather DMA engine.
590 <chapter id="intfunctions">
591 <title>Internal Functions</title>
592 !Isound/oss/via82cxxx_audio.c