aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/via-audio.tmpl
blob: 36e642147d6b2d2be27873aa86555ff8a32b3788 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
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>