Documentation/DocBook/via-audio.tmpl

   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>
 228 Version 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>
 253 Version 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>
 326 Version 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>
 338 Version 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>
 350 Version 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>
 369 Version 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>
 381 Version 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>
 479 Version 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>
 502 Version 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>
 515 Version 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/sound
 541         </para>
 542    </listitem>
 543   </itemizedlist>
 544 </sect1>
 545
 546 <sect1 id="version115"><title>
 547 Version 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>
 574 Version 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 !Isound/oss/via82cxxx_audio.c
 591   </chapter>
 592
 593 </book>
 594
 595