1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
2
3<book id="ViaAudioGuide">
4 <bookinfo>
5  <title>Via 686 Audio Driver for Linux</title>
6  
7  <authorgroup>
8   <author>
9    <firstname>Jeff</firstname>
10    <surname>Garzik</surname>
11   </author>
12  </authorgroup>
13
14  <copyright>
15   <year>1999-2001</year>
16   <holder>Jeff Garzik</holder>
17  </copyright>
18
19  <legalnotice>
20   <para>
21     This documentation is free software; you can redistribute
22     it and/or modify it under the terms of the GNU General Public
23     License as published by the Free Software Foundation; either
24     version 2 of the License, or (at your option) any later
25     version.
26   </para>
27      
28   <para>
29     This program is distributed in the hope that it will be
30     useful, but WITHOUT ANY WARRANTY; without even the implied
31     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
32     See the GNU General Public License for more details.
33   </para>
34      
35   <para>
36     You should have received a copy of the GNU General Public
37     License along with this program; if not, write to the Free
38     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
39     MA 02111-1307 USA
40   </para>
41      
42   <para>
43     For more details see the file COPYING in the source
44     distribution of Linux.
45   </para>
46  </legalnotice>
47 </bookinfo>
48
49<toc></toc>
50
51  <chapter id="intro">
52      <title>Introduction</title>
53  <para>
54  	The Via VT82C686A "super southbridge" chips contain
55	AC97-compatible audio logic which features dual 16-bit stereo
56	PCM sound channels (full duplex), plus a third PCM channel intended for use
57	in hardware-assisted FM synthesis.
58  </para>
59  <para>
60  	The current Linux kernel audio driver for this family of chips
61	supports audio playback and recording, but hardware-assisted
62	FM features, and hardware buffer direct-access (mmap)
63	support are not yet available.
64  </para>
65  <para>
66  	This driver supports any Linux kernel version after 2.4.10.
67  </para>
68  <para>
69	Please send bug reports to the mailing list <email>linux-via@gtf.org</email>.
70	To subscribe, e-mail <email>majordomo@gtf.org</email> with
71  </para>
72  <programlisting>
73	subscribe linux-via
74  </programlisting>
75  <para>
76	in the body of the message.
77  </para>
78  </chapter>
79  
80  <chapter id="install">
81      <title>Driver Installation</title>
82  <para>
83  	To use this audio driver, select the
84	CONFIG_SOUND_VIA82CXXX option in the section Sound during kernel configuration.
85	Follow the usual kernel procedures for rebuilding the kernel,
86	or building and installing driver modules.
87  </para>
88  <para>
89  	To make this driver the default audio driver, you can add the
90	following to your /etc/conf.modules file:
91  </para>
92  <programlisting>
93	alias sound via82cxxx_audio
94  </programlisting>
95  <para>
96  	Note that soundcore and ac97_codec support modules
97	are also required for working audio, in addition to
98	the via82cxxx_audio module itself.
99  </para>
100  </chapter>
101  
102  <chapter id="reportbug">
103      <title>Submitting a bug report</title>
104  <sect1 id="bugrepdesc"><title>Description of problem</title>
105  <para>
106	Describe the application you were using to play/record sound, and how
107	to reproduce the problem.
108  </para>
109  </sect1>
110  <sect1 id="bugrepdiag"><title>Diagnostic output</title>
111  <para>
112	Obtain the via-audio-diag diagnostics program from
113	http://sf.net/projects/gkernel/ and provide a dump of the
114	audio chip's registers while the problem is occurring.  Sample command line:
115  </para>
116  <programlisting>
117	./via-audio-diag -aps > diag-output.txt
118  </programlisting>
119  </sect1>
120  <sect1 id="bugrepdebug"><title>Driver debug output</title>
121  <para>
122	Define <constant>VIA_DEBUG</constant> at the beginning of the driver, then capture and email
123	the kernel log output.  This can be viewed in the system kernel log (if
124	enabled), or via the dmesg program.  Sample command line:
125  </para>
126  <programlisting>
127	dmesg > /tmp/dmesg-output.txt
128  </programlisting>
129  </sect1>
130  <sect1 id="bugrepprintk"><title>Bigger kernel message buffer</title>
131  <para>
132	If you wish to increase the size of the buffer displayed by dmesg, then
133	change the <constant>LOG_BUF_LEN</constant> macro at the top of linux/kernel/printk.c, recompile
134	your kernel, and pass the <constant>LOG_BUF_LEN</constant> value to dmesg.  Sample command line with
135	<constant>LOG_BUF_LEN</constant> == 32768:
136  </para>
137  <programlisting>
138	dmesg -s 32768 > /tmp/dmesg-output.txt
139  </programlisting>
140  </sect1>
141  </chapter>
142  
143  <chapter id="bugs">
144     <title>Known Bugs And Assumptions</title>
145  <para>
146  <variablelist>
147    <varlistentry><term>Low volume</term>
148    <listitem>
149    <para>
150	Volume too low on many systems.  Workaround:  use mixer program
151	such as xmixer to increase volume.
152    </para>
153    </listitem></varlistentry>
154
155  </variablelist>
156	
157  </para>
158  </chapter>
159
160  <chapter id="thanks">
161      <title>Thanks</title>
162  <para>
163	Via for providing e-mail support, specs, and NDA'd source code.
164  </para>
165  <para>
166	MandrakeSoft for providing hacking time.
167  </para>
168  <para>
169	AC97 mixer interface fixes and debugging by Ron Cemer <email>roncemer@gte.net</email>.
170  </para>
171  <para>
172	Rui Sousa <email>rui.sousa@conexant.com</email>, for bugfixing
173	MMAP support, and several other notable fixes that resulted from
174	his hard work and testing.
175  </para>
176  <para>
177	Adrian Cox <email>adrian@humboldt.co.uk</email>, for bugfixing
178	MMAP support, and several other notable fixes that resulted from
179	his hard work and testing.
180  </para>
181  <para>
182  	Thomas Sailer for further bugfixes.
183  </para>
184  </chapter>
185  
186  <chapter id="notes">
187     <title>Random Notes</title>
188  <para>
189	Two /proc pseudo-files provide diagnostic information.  This is generally
190	not useful to most users.  Power users can disable CONFIG_SOUND_VIA82CXXX_PROCFS,
191	and remove the /proc support code.  Once
192	version 2.0.0 is released, the /proc support code will be disabled by
193	default.  Available /proc pseudo-files:
194  </para>
195  <programlisting>
196	/proc/driver/via/0/info
197	/proc/driver/via/0/ac97
198  </programlisting>
199  <para>
200	This driver by default supports all PCI audio devices which report
201	a vendor id of 0x1106, and a device id of 0x3058.  Subsystem vendor
202	and device ids are not examined.
203  </para>
204  <para>
205	GNU indent formatting options:
206  <programlisting>
207-kr -i8 -ts8 -br -ce -bap -sob -l80 -pcs -cs -ss -bs -di1 -nbc -lp -psl
208  </programlisting>
209  </para>
210  <para>
211	Via has graciously donated e-mail support and source code to help further
212	the development of this driver.  Their assistance has been invaluable
213	in the design and coding of the next major version of this driver.
214  </para>
215  <para>
216	The Via audio chip apparently provides a second PCM scatter-gather
217	DMA channel just for FM data, but does not have a full hardware MIDI
218	processor.  I haven't put much thought towards a solution here, but it
219	might involve using SoftOSS midi wave table, or simply disabling MIDI
220	support altogether and using the FM PCM channel as a second (input? output?)
221  </para>
222  </chapter>
223
224  <chapter id="changelog">
225      <title>Driver ChangeLog</title>
226
227<sect1 id="version191"><title>
228Version 1.9.1
229</title>
230  <itemizedlist spacing=compact>
231   <listitem>
232    <para>
233    DSP read/write bugfixes from Thomas Sailer.
234    </para>
235   </listitem>
236
237   <listitem>
238    <para>
239    Add new PCI id for single-channel use of Via 8233.
240    </para>
241   </listitem>
242
243   <listitem>
244    <para>
245    Other bug fixes, tweaks, new ioctls.
246    </para>
247   </listitem>
248
249  </itemizedlist>
250</sect1>
251
252<sect1 id="version1115"><title>
253Version 1.1.15
254</title>
255  <itemizedlist spacing=compact>
256   <listitem>
257    <para>
258    Support for variable fragment size and variable fragment number (Rui
259    Sousa)
260    </para>
261   </listitem>
262
263   <listitem>
264    <para>
265    Fixes for the SPEED, STEREO, CHANNELS, FMT ioctls when in read &
266    write mode (Rui Sousa)
267    </para>
268   </listitem>
269
270   <listitem>
271    <para>
272    Mmaped sound is now fully functional. (Rui Sousa)
273    </para>
274   </listitem>
275
276   <listitem>
277    <para>
278    Make sure to enable PCI device before reading any of its PCI
279    config information. (fixes potential hotplug problems)
280    </para>
281   </listitem>
282
283   <listitem>
284    <para>
285    Clean up code a bit and add more internal function documentation.
286    </para>
287   </listitem>
288
289   <listitem>
290    <para>
291    AC97 codec access fixes (Adrian Cox)
292    </para>
293   </listitem>
294
295   <listitem>
296    <para>
297    Big endian fixes (Adrian Cox)
298    </para>
299   </listitem>
300
301   <listitem>
302    <para>
303    MIDI support (Adrian Cox)
304    </para>
305   </listitem>
306
307   <listitem>
308    <para>
309    Detect and report locked-rate AC97 codecs.  If your hardware only
310    supports 48Khz (locked rate), then your recording/playback software
311    must upsample or downsample accordingly.  The hardware cannot do it.
312    </para>
313   </listitem>
314
315   <listitem>
316    <para>
317    Use new pci_request_regions and pci_disable_device functions in
318    kernel 2.4.6.
319    </para>
320   </listitem>
321
322  </itemizedlist>
323</sect1>
324
325<sect1 id="version1114"><title>
326Version 1.1.14
327</title>
328  <itemizedlist spacing=compact>
329   <listitem>
330    <para>
331    Use VM_RESERVE when available, to eliminate unnecessary page faults.
332    </para>
333   </listitem>
334  </itemizedlist>
335</sect1>
336
337<sect1 id="version1112"><title>
338Version 1.1.12
339</title>
340  <itemizedlist spacing=compact>
341   <listitem>
342    <para>
343    mmap bug fixes from Linus.
344    </para>
345   </listitem>
346  </itemizedlist>
347</sect1>
348
349<sect1 id="version1111"><title>
350Version 1.1.11
351</title>
352  <itemizedlist spacing=compact>
353   <listitem>
354    <para>
355    Many more bug fixes.  mmap enabled by default, but may still be buggy.
356    </para>
357   </listitem>
358
359   <listitem>
360    <para>
361    Uses new and spiffy method of mmap'ing the DMA buffer, based
362    on a suggestion from Linus.
363    </para>
364   </listitem>
365  </itemizedlist>
366</sect1>
367
368<sect1 id="version1110"><title>
369Version 1.1.10
370</title>
371  <itemizedlist spacing=compact>
372   <listitem>
373    <para>
374    Many bug fixes.  mmap enabled by default, but may still be buggy.
375    </para>
376   </listitem>
377  </itemizedlist>
378</sect1>
379
380<sect1 id="version119"><title>
381Version 1.1.9
382</title>
383  <itemizedlist spacing=compact>
384   <listitem>
385    <para>
386    Redesign and rewrite audio playback implementation.  (faster and smaller, hopefully)
387    </para>
388   </listitem>
389
390   <listitem>
391    <para>
392    Implement recording and full duplex (DSP_CAP_DUPLEX) support.
393    </para>
394   </listitem>
395
396   <listitem>
397    <para>
398    Make procfs support optional.
399    </para>
400   </listitem>
401
402   <listitem>
403    <para>
404    Quick interrupt status check, to lessen overhead in interrupt
405    sharing situations.
406    </para>
407   </listitem>
408
409   <listitem>
410    <para>
411    Add mmap(2) support.  Disabled for now, it is still buggy and experimental.
412    </para>
413   </listitem>
414
415   <listitem>
416    <para>
417    Surround all syscalls with a semaphore for cheap and easy SMP protection.
418    </para>
419   </listitem>
420
421   <listitem>
422    <para>
423    Fix bug in channel shutdown (hardware channel reset) code.
424    </para>
425   </listitem>
426
427   <listitem>
428    <para>
429    Remove unnecessary spinlocks (better performance).
430    </para>
431   </listitem>
432
433   <listitem>
434    <para>
435    Eliminate "unknown AFMT" message by using a different method
436    of selecting the best AFMT_xxx sound sample format for use.
437    </para>
438   </listitem>
439
440   <listitem>
441    <para>
442    Support for realtime hardware pointer position reporting
443    (DSP_CAP_REALTIME, SNDCTL_DSP_GETxPTR ioctls)
444    </para>
445   </listitem>
446
447   <listitem>
448    <para>
449    Support for capture/playback triggering
450    (DSP_CAP_TRIGGER, SNDCTL_DSP_SETTRIGGER ioctls)
451    </para>
452   </listitem>
453
454   <listitem>
455    <para>
456    SNDCTL_DSP_SETDUPLEX and SNDCTL_DSP_POST ioctls now handled.
457    </para>
458   </listitem>
459
460   <listitem>
461    <para>
462    Rewrite open(2) and close(2) logic to allow only one user at
463    a time.  All other open(2) attempts will sleep until they succeed.
464    FIXME: open(O_RDONLY) and open(O_WRONLY) should be allowed to succeed.
465    </para>
466   </listitem>
467
468   <listitem>
469    <para>
470    Reviewed code to ensure that SMP and multiple audio devices
471    are fully supported.
472    </para>
473   </listitem>
474
475  </itemizedlist>
476</sect1>
477
478<sect1 id="version118"><title>
479Version 1.1.8
480</title>
481  <itemizedlist spacing=compact>
482   <listitem>
483    <para>
484    	Clean up interrupt handler output.  Fixes the following kernel error message:
485    </para>
486  	<programlisting>
487	unhandled interrupt ...
488  	</programlisting>
489   </listitem>
490
491   <listitem>
492    <para>
493    	Convert documentation to DocBook, so that PDF, HTML and PostScript (.ps) output is readily
494	available.
495    </para>
496   </listitem>
497
498  </itemizedlist>
499</sect1>
500
501<sect1 id="version117"><title>
502Version 1.1.7
503</title>
504  <itemizedlist spacing=compact>
505   <listitem>
506    <para>
507 Fix module unload bug where mixer device left registered
508  after driver exit
509    </para>
510   </listitem>
511  </itemizedlist>
512</sect1>
513
514<sect1 id="version116"><title>
515Version 1.1.6
516</title>
517  <itemizedlist spacing=compact>
518   <listitem>
519    <para>
520 Rewrite via_set_rate to mimic ALSA basic AC97 rate setting
521    </para>
522   </listitem>
523   <listitem>
524    <para>
525 Remove much dead code
526    </para>
527   </listitem>
528   <listitem>
529    <para>
530 Complete spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl
531    </para>
532   </listitem>
533   <listitem>
534    <para>
535 Fix build problem in via_dsp_ioctl
536    </para>
537   </listitem>
538   <listitem>
539    <para>
540 Optimize included headers to eliminate headers found in linux/drivers/sound
541	</para>
542   </listitem>
543  </itemizedlist>
544</sect1>
545
546<sect1 id="version115"><title>
547Version 1.1.5
548</title>
549  <itemizedlist spacing=compact>
550   <listitem>
551    <para>
552 Disable some overly-verbose debugging code
553    </para>
554   </listitem>
555   <listitem>
556    <para>
557 Remove unnecessary sound locks
558   </para>
559   </listitem>
560   <listitem>
561    <para>
562 Fix some ioctls for better time resolution
563    </para>
564   </listitem>
565   <listitem>
566    <para>
567 Begin spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl
568    </para>
569   </listitem>
570  </itemizedlist>
571</sect1>
572
573<sect1 id="version114"><title>
574Version 1.1.4
575</title>
576  <itemizedlist spacing=compact>
577   <listitem>
578    <para>
579 Completed rewrite of driver.  Eliminated SoundBlaster compatibility
580  completely, and now uses the much-faster scatter-gather DMA engine.
581    </para>
582   </listitem>
583  </itemizedlist>
584</sect1>
585
586  </chapter>
587  
588  <chapter id="intfunctions">
589     <title>Internal Functions</title>
590!Idrivers/sound/via82cxxx_audio.c
591  </chapter>
592
593</book>
594