SAFE public projects git trees. - safe/jmp/linux-2.6/blob - 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