[PATCH] DocBook: use <informalexample> for examples
[linux-2.6.git] / Documentation / DocBook / via-audio.tmpl
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" []>
4
5 <book id="ViaAudioGuide">
6  <bookinfo>
7   <title>Via 686 Audio Driver for Linux</title>
8   
9   <authorgroup>
10    <author>
11     <firstname>Jeff</firstname>
12     <surname>Garzik</surname>
13    </author>
14   </authorgroup>
15
16   <copyright>
17    <year>1999-2001</year>
18    <holder>Jeff Garzik</holder>
19   </copyright>
20
21   <legalnotice>
22    <para>
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
27      version.
28    </para>
29       
30    <para>
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.
35    </para>
36       
37    <para>
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,
41      MA 02111-1307 USA
42    </para>
43       
44    <para>
45      For more details see the file COPYING in the source
46      distribution of Linux.
47    </para>
48   </legalnotice>
49  </bookinfo>
50
51 <toc></toc>
52
53   <chapter id="intro">
54       <title>Introduction</title>
55   <para>
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.
60   </para>
61   <para>
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.
66   </para>
67   <para>
68         This driver supports any Linux kernel version after 2.4.10.
69   </para>
70   <para>
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
73   </para>
74   <programlisting>
75         subscribe linux-via
76   </programlisting>
77   <para>
78         in the body of the message.
79   </para>
80   </chapter>
81   
82   <chapter id="install">
83       <title>Driver Installation</title>
84   <para>
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.
89   </para>
90   <para>
91         To make this driver the default audio driver, you can add the
92         following to your /etc/conf.modules file:
93   </para>
94   <programlisting>
95         alias sound via82cxxx_audio
96   </programlisting>
97   <para>
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.
101   </para>
102   </chapter>
103   
104   <chapter id="reportbug">
105       <title>Submitting a bug report</title>
106   <sect1 id="bugrepdesc"><title>Description of problem</title>
107   <para>
108         Describe the application you were using to play/record sound, and how
109         to reproduce the problem.
110   </para>
111   </sect1>
112   <sect1 id="bugrepdiag"><title>Diagnostic output</title>
113   <para>
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:
117   </para>
118   <programlisting>
119         ./via-audio-diag -aps > diag-output.txt
120   </programlisting>
121   </sect1>
122   <sect1 id="bugrepdebug"><title>Driver debug output</title>
123   <para>
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:
127   </para>
128   <programlisting>
129         dmesg > /tmp/dmesg-output.txt
130   </programlisting>
131   </sect1>
132   <sect1 id="bugrepprintk"><title>Bigger kernel message buffer</title>
133   <para>
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:
138   </para>
139   <programlisting>
140         dmesg -s 32768 > /tmp/dmesg-output.txt
141   </programlisting>
142   </sect1>
143   </chapter>
144   
145   <chapter id="bugs">
146      <title>Known Bugs And Assumptions</title>
147   <para>
148   <variablelist>
149     <varlistentry><term>Low volume</term>
150     <listitem>
151     <para>
152         Volume too low on many systems.  Workaround:  use mixer program
153         such as xmixer to increase volume.
154     </para>
155     </listitem></varlistentry>
156
157   </variablelist>
158         
159   </para>
160   </chapter>
161
162   <chapter id="thanks">
163       <title>Thanks</title>
164   <para>
165         Via for providing e-mail support, specs, and NDA'd source code.
166   </para>
167   <para>
168         MandrakeSoft for providing hacking time.
169   </para>
170   <para>
171         AC97 mixer interface fixes and debugging by Ron Cemer <email>roncemer@gte.net</email>.
172   </para>
173   <para>
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.
177   </para>
178   <para>
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.
182   </para>
183   <para>
184         Thomas Sailer for further bugfixes.
185   </para>
186   </chapter>
187   
188   <chapter id="notes">
189      <title>Random Notes</title>
190   <para>
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:
196   </para>
197   <programlisting>
198         /proc/driver/via/0/info
199         /proc/driver/via/0/ac97
200   </programlisting>
201   <para>
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.
205   </para>
206   <para>
207         GNU indent formatting options:
208   <programlisting>
209 -kr -i8 -ts8 -br -ce -bap -sob -l80 -pcs -cs -ss -bs -di1 -nbc -lp -psl
210   </programlisting>
211   </para>
212   <para>
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.
216   </para>
217   <para>
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?)
223   </para>
224   </chapter>
225
226   <chapter id="changelog">
227       <title>Driver ChangeLog</title>
228
229 <sect1 id="version191"><title>
230 Version 1.9.1
231 </title>
232   <itemizedlist spacing="compact">
233    <listitem>
234     <para>
235     DSP read/write bugfixes from Thomas Sailer.
236     </para>
237    </listitem>
238
239    <listitem>
240     <para>
241     Add new PCI id for single-channel use of Via 8233.
242     </para>
243    </listitem>
244
245    <listitem>
246     <para>
247     Other bug fixes, tweaks, new ioctls.
248     </para>
249    </listitem>
250
251   </itemizedlist>
252 </sect1>
253
254 <sect1 id="version1115"><title>
255 Version 1.1.15
256 </title>
257   <itemizedlist spacing="compact">
258    <listitem>
259     <para>
260     Support for variable fragment size and variable fragment number (Rui
261     Sousa)
262     </para>
263    </listitem>
264
265    <listitem>
266     <para>
267     Fixes for the SPEED, STEREO, CHANNELS, FMT ioctls when in read &amp;
268     write mode (Rui Sousa)
269     </para>
270    </listitem>
271
272    <listitem>
273     <para>
274     Mmaped sound is now fully functional. (Rui Sousa)
275     </para>
276    </listitem>
277
278    <listitem>
279     <para>
280     Make sure to enable PCI device before reading any of its PCI
281     config information. (fixes potential hotplug problems)
282     </para>
283    </listitem>
284
285    <listitem>
286     <para>
287     Clean up code a bit and add more internal function documentation.
288     </para>
289    </listitem>
290
291    <listitem>
292     <para>
293     AC97 codec access fixes (Adrian Cox)
294     </para>
295    </listitem>
296
297    <listitem>
298     <para>
299     Big endian fixes (Adrian Cox)
300     </para>
301    </listitem>
302
303    <listitem>
304     <para>
305     MIDI support (Adrian Cox)
306     </para>
307    </listitem>
308
309    <listitem>
310     <para>
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.
314     </para>
315    </listitem>
316
317    <listitem>
318     <para>
319     Use new pci_request_regions and pci_disable_device functions in
320     kernel 2.4.6.
321     </para>
322    </listitem>
323
324   </itemizedlist>
325 </sect1>
326
327 <sect1 id="version1114"><title>
328 Version 1.1.14
329 </title>
330   <itemizedlist spacing="compact">
331    <listitem>
332     <para>
333     Use VM_RESERVE when available, to eliminate unnecessary page faults.
334     </para>
335    </listitem>
336   </itemizedlist>
337 </sect1>
338
339 <sect1 id="version1112"><title>
340 Version 1.1.12
341 </title>
342   <itemizedlist spacing="compact">
343    <listitem>
344     <para>
345     mmap bug fixes from Linus.
346     </para>
347    </listitem>
348   </itemizedlist>
349 </sect1>
350
351 <sect1 id="version1111"><title>
352 Version 1.1.11
353 </title>
354   <itemizedlist spacing="compact">
355    <listitem>
356     <para>
357     Many more bug fixes.  mmap enabled by default, but may still be buggy.
358     </para>
359    </listitem>
360
361    <listitem>
362     <para>
363     Uses new and spiffy method of mmap'ing the DMA buffer, based
364     on a suggestion from Linus.
365     </para>
366    </listitem>
367   </itemizedlist>
368 </sect1>
369
370 <sect1 id="version1110"><title>
371 Version 1.1.10
372 </title>
373   <itemizedlist spacing="compact">
374    <listitem>
375     <para>
376     Many bug fixes.  mmap enabled by default, but may still be buggy.
377     </para>
378    </listitem>
379   </itemizedlist>
380 </sect1>
381
382 <sect1 id="version119"><title>
383 Version 1.1.9
384 </title>
385   <itemizedlist spacing="compact">
386    <listitem>
387     <para>
388     Redesign and rewrite audio playback implementation.  (faster and smaller, hopefully)
389     </para>
390    </listitem>
391
392    <listitem>
393     <para>
394     Implement recording and full duplex (DSP_CAP_DUPLEX) support.
395     </para>
396    </listitem>
397
398    <listitem>
399     <para>
400     Make procfs support optional.
401     </para>
402    </listitem>
403
404    <listitem>
405     <para>
406     Quick interrupt status check, to lessen overhead in interrupt
407     sharing situations.
408     </para>
409    </listitem>
410
411    <listitem>
412     <para>
413     Add mmap(2) support.  Disabled for now, it is still buggy and experimental.
414     </para>
415    </listitem>
416
417    <listitem>
418     <para>
419     Surround all syscalls with a semaphore for cheap and easy SMP protection.
420     </para>
421    </listitem>
422
423    <listitem>
424     <para>
425     Fix bug in channel shutdown (hardware channel reset) code.
426     </para>
427    </listitem>
428
429    <listitem>
430     <para>
431     Remove unnecessary spinlocks (better performance).
432     </para>
433    </listitem>
434
435    <listitem>
436     <para>
437     Eliminate "unknown AFMT" message by using a different method
438     of selecting the best AFMT_xxx sound sample format for use.
439     </para>
440    </listitem>
441
442    <listitem>
443     <para>
444     Support for realtime hardware pointer position reporting
445     (DSP_CAP_REALTIME, SNDCTL_DSP_GETxPTR ioctls)
446     </para>
447    </listitem>
448
449    <listitem>
450     <para>
451     Support for capture/playback triggering
452     (DSP_CAP_TRIGGER, SNDCTL_DSP_SETTRIGGER ioctls)
453     </para>
454    </listitem>
455
456    <listitem>
457     <para>
458     SNDCTL_DSP_SETDUPLEX and SNDCTL_DSP_POST ioctls now handled.
459     </para>
460    </listitem>
461
462    <listitem>
463     <para>
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.
467     </para>
468    </listitem>
469
470    <listitem>
471     <para>
472     Reviewed code to ensure that SMP and multiple audio devices
473     are fully supported.
474     </para>
475    </listitem>
476
477   </itemizedlist>
478 </sect1>
479
480 <sect1 id="version118"><title>
481 Version 1.1.8
482 </title>
483   <itemizedlist spacing="compact">
484    <listitem>
485     <para>
486         Clean up interrupt handler output.  Fixes the following kernel error message:
487     </para>
488         <programlisting>
489         unhandled interrupt ...
490         </programlisting>
491    </listitem>
492
493    <listitem>
494     <para>
495         Convert documentation to DocBook, so that PDF, HTML and PostScript (.ps) output is readily
496         available.
497     </para>
498    </listitem>
499
500   </itemizedlist>
501 </sect1>
502
503 <sect1 id="version117"><title>
504 Version 1.1.7
505 </title>
506   <itemizedlist spacing="compact">
507    <listitem>
508     <para>
509  Fix module unload bug where mixer device left registered
510   after driver exit
511     </para>
512    </listitem>
513   </itemizedlist>
514 </sect1>
515
516 <sect1 id="version116"><title>
517 Version 1.1.6
518 </title>
519   <itemizedlist spacing="compact">
520    <listitem>
521     <para>
522  Rewrite via_set_rate to mimic ALSA basic AC97 rate setting
523     </para>
524    </listitem>
525    <listitem>
526     <para>
527  Remove much dead code
528     </para>
529    </listitem>
530    <listitem>
531     <para>
532  Complete spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl
533     </para>
534    </listitem>
535    <listitem>
536     <para>
537  Fix build problem in via_dsp_ioctl
538     </para>
539    </listitem>
540    <listitem>
541     <para>
542  Optimize included headers to eliminate headers found in linux/sound
543         </para>
544    </listitem>
545   </itemizedlist>
546 </sect1>
547
548 <sect1 id="version115"><title>
549 Version 1.1.5
550 </title>
551   <itemizedlist spacing="compact">
552    <listitem>
553     <para>
554  Disable some overly-verbose debugging code
555     </para>
556    </listitem>
557    <listitem>
558     <para>
559  Remove unnecessary sound locks
560    </para>
561    </listitem>
562    <listitem>
563     <para>
564  Fix some ioctls for better time resolution
565     </para>
566    </listitem>
567    <listitem>
568     <para>
569  Begin spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl
570     </para>
571    </listitem>
572   </itemizedlist>
573 </sect1>
574
575 <sect1 id="version114"><title>
576 Version 1.1.4
577 </title>
578   <itemizedlist spacing="compact">
579    <listitem>
580     <para>
581  Completed rewrite of driver.  Eliminated SoundBlaster compatibility
582   completely, and now uses the much-faster scatter-gather DMA engine.
583     </para>
584    </listitem>
585   </itemizedlist>
586 </sect1>
587
588   </chapter>
589   
590   <chapter id="intfunctions">
591      <title>Internal Functions</title>
592 !Isound/oss/via82cxxx_audio.c
593   </chapter>
594
595 </book>
596
597