1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]> 2 3<book id="ViaAudioGuide"> 4 <bookinfo> 5 <title>Via 686/8233/8235 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. The VIA VT8233/8235 extends this 58 support to include six channel output and additional record 59 facilities. 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. The 8233 support covers all devices 205 with a device id of 0x3059 and vendor id of 0x1106. Again subsystem 206 ids are ignored as they usually hold the AC97 codec vendor information. 207 </para> 208 <para> 209 GNU indent formatting options: 210 <programlisting> 211-kr -i8 -ts8 -br -ce -bap -sob -l80 -pcs -cs -ss -bs -di1 -nbc -lp -psl 212 </programlisting> 213 </para> 214 <para> 215 Via has graciously donated e-mail support and source code to help further 216 the development of this driver. Their assistance has been invaluable 217 in the design and coding of the next major version of this driver. 218 </para> 219 <para> 220 The Via audio chip apparently provides a second PCM scatter-gather 221 DMA channel just for FM data, but does not have a full hardware MIDI 222 processor. I haven't put much thought towards a solution here, but it 223 might involve using SoftOSS midi wave table, or simply disabling MIDI 224 support altogether and using the FM PCM channel as a second (input? output?) 225 </para> 226 </chapter> 227 228 <chapter id="changelog"> 229 <title>Driver ChangeLog</title> 230 231<sect1 id="version191ac"><title> 232Version 1.9.1-ac 233</title> 234 <itemizedlist spacing=compact> 235 <listitem> 236 <para> 237 Added VIA 8233/8235 support including six channel support. We don't 238 yet support S/PDIF, EAPD, using the second DSP channel and FM channels 239 as extra dsp devices, or the extra record channel. New features tested 240 on a VIA EPIA-M kindly provided by VIA. 241 </para> 242 </listitem> 243 </itemizedlist> 244</sect1> 245 246<sect1 id="version191"><title> 247Version 1.9.1 248</title> 249 <itemizedlist spacing=compact> 250 <listitem> 251 <para> 252 DSP read/write bugfixes from Thomas Sailer. 253 </para> 254 </listitem> 255 256 <listitem> 257 <para> 258 Add new PCI id for single-channel use of Via 8233. 259 </para> 260 </listitem> 261 262 <listitem> 263 <para> 264 Other bug fixes, tweaks, new ioctls. 265 </para> 266 </listitem> 267 268 </itemizedlist> 269</sect1> 270 271<sect1 id="version1115"><title> 272Version 1.1.15 273</title> 274 <itemizedlist spacing=compact> 275 <listitem> 276 <para> 277 Support for variable fragment size and variable fragment number (Rui 278 Sousa) 279 </para> 280 </listitem> 281 282 <listitem> 283 <para> 284 Fixes for the SPEED, STEREO, CHANNELS, FMT ioctls when in read & 285 write mode (Rui Sousa) 286 </para> 287 </listitem> 288 289 <listitem> 290 <para> 291 Mmaped sound is now fully functional. (Rui Sousa) 292 </para> 293 </listitem> 294 295 <listitem> 296 <para> 297 Make sure to enable PCI device before reading any of its PCI 298 config information. (fixes potential hotplug problems) 299 </para> 300 </listitem> 301 302 <listitem> 303 <para> 304 Clean up code a bit and add more internal function documentation. 305 </para> 306 </listitem> 307 308 <listitem> 309 <para> 310 AC97 codec access fixes (Adrian Cox) 311 </para> 312 </listitem> 313 314 <listitem> 315 <para> 316 Big endian fixes (Adrian Cox) 317 </para> 318 </listitem> 319 320 <listitem> 321 <para> 322 MIDI support (Adrian Cox) 323 </para> 324 </listitem> 325 326 <listitem> 327 <para> 328 Detect and report locked-rate AC97 codecs. If your hardware only 329 supports 48Khz (locked rate), then your recording/playback software 330 must upsample or downsample accordingly. The hardware cannot do it. 331 </para> 332 </listitem> 333 334 <listitem> 335 <para> 336 Use new pci_request_regions and pci_disable_device functions in 337 kernel 2.4.6. 338 </para> 339 </listitem> 340 341 </itemizedlist> 342</sect1> 343 344<sect1 id="version1114"><title> 345Version 1.1.14 346</title> 347 <itemizedlist spacing=compact> 348 <listitem> 349 <para> 350 Use VM_RESERVE when available, to eliminate unnecessary page faults. 351 </para> 352 </listitem> 353 </itemizedlist> 354</sect1> 355 356<sect1 id="version1112"><title> 357Version 1.1.12 358</title> 359 <itemizedlist spacing=compact> 360 <listitem> 361 <para> 362 mmap bug fixes from Linus. 363 </para> 364 </listitem> 365 </itemizedlist> 366</sect1> 367 368<sect1 id="version1111"><title> 369Version 1.1.11 370</title> 371 <itemizedlist spacing=compact> 372 <listitem> 373 <para> 374 Many more bug fixes. mmap enabled by default, but may still be buggy. 375 </para> 376 </listitem> 377 378 <listitem> 379 <para> 380 Uses new and spiffy method of mmap'ing the DMA buffer, based 381 on a suggestion from Linus. 382 </para> 383 </listitem> 384 </itemizedlist> 385</sect1> 386 387<sect1 id="version1110"><title> 388Version 1.1.10 389</title> 390 <itemizedlist spacing=compact> 391 <listitem> 392 <para> 393 Many bug fixes. mmap enabled by default, but may still be buggy. 394 </para> 395 </listitem> 396 </itemizedlist> 397</sect1> 398 399<sect1 id="version119"><title> 400Version 1.1.9 401</title> 402 <itemizedlist spacing=compact> 403 <listitem> 404 <para> 405 Redesign and rewrite audio playback implementation. (faster and smaller, hopefully) 406 </para> 407 </listitem> 408 409 <listitem> 410 <para> 411 Implement recording and full duplex (DSP_CAP_DUPLEX) support. 412 </para> 413 </listitem> 414 415 <listitem> 416 <para> 417 Make procfs support optional. 418 </para> 419 </listitem> 420 421 <listitem> 422 <para> 423 Quick interrupt status check, to lessen overhead in interrupt 424 sharing situations. 425 </para> 426 </listitem> 427 428 <listitem> 429 <para> 430 Add mmap(2) support. Disabled for now, it is still buggy and experimental. 431 </para> 432 </listitem> 433 434 <listitem> 435 <para> 436 Surround all syscalls with a semaphore for cheap and easy SMP protection. 437 </para> 438 </listitem> 439 440 <listitem> 441 <para> 442 Fix bug in channel shutdown (hardware channel reset) code. 443 </para> 444 </listitem> 445 446 <listitem> 447 <para> 448 Remove unnecessary spinlocks (better performance). 449 </para> 450 </listitem> 451 452 <listitem> 453 <para> 454 Eliminate "unknown AFMT" message by using a different method 455 of selecting the best AFMT_xxx sound sample format for use. 456 </para> 457 </listitem> 458 459 <listitem> 460 <para> 461 Support for realtime hardware pointer position reporting 462 (DSP_CAP_REALTIME, SNDCTL_DSP_GETxPTR ioctls) 463 </para> 464 </listitem> 465 466 <listitem> 467 <para> 468 Support for capture/playback triggering 469 (DSP_CAP_TRIGGER, SNDCTL_DSP_SETTRIGGER ioctls) 470 </para> 471 </listitem> 472 473 <listitem> 474 <para> 475 SNDCTL_DSP_SETDUPLEX and SNDCTL_DSP_POST ioctls now handled. 476 </para> 477 </listitem> 478 479 <listitem> 480 <para> 481 Rewrite open(2) and close(2) logic to allow only one user at 482 a time. All other open(2) attempts will sleep until they succeed. 483 FIXME: open(O_RDONLY) and open(O_WRONLY) should be allowed to succeed. 484 </para> 485 </listitem> 486 487 <listitem> 488 <para> 489 Reviewed code to ensure that SMP and multiple audio devices 490 are fully supported. 491 </para> 492 </listitem> 493 494 </itemizedlist> 495</sect1> 496 497<sect1 id="version118"><title> 498Version 1.1.8 499</title> 500 <itemizedlist spacing=compact> 501 <listitem> 502 <para> 503 Clean up interrupt handler output. Fixes the following kernel error message: 504 </para> 505 <programlisting> 506 unhandled interrupt ... 507 </programlisting> 508 </listitem> 509 510 <listitem> 511 <para> 512 Convert documentation to DocBook, so that PDF, HTML and PostScript (.ps) output is readily 513 available. 514 </para> 515 </listitem> 516 517 </itemizedlist> 518</sect1> 519 520<sect1 id="version117"><title> 521Version 1.1.7 522</title> 523 <itemizedlist spacing=compact> 524 <listitem> 525 <para> 526 Fix module unload bug where mixer device left registered 527 after driver exit 528 </para> 529 </listitem> 530 </itemizedlist> 531</sect1> 532 533<sect1 id="version116"><title> 534Version 1.1.6 535</title> 536 <itemizedlist spacing=compact> 537 <listitem> 538 <para> 539 Rewrite via_set_rate to mimic ALSA basic AC97 rate setting 540 </para> 541 </listitem> 542 <listitem> 543 <para> 544 Remove much dead code 545 </para> 546 </listitem> 547 <listitem> 548 <para> 549 Complete spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl 550 </para> 551 </listitem> 552 <listitem> 553 <para> 554 Fix build problem in via_dsp_ioctl 555 </para> 556 </listitem> 557 <listitem> 558 <para> 559 Optimize included headers to eliminate headers found in linux/drivers/sound 560 </para> 561 </listitem> 562 </itemizedlist> 563</sect1> 564 565<sect1 id="version115"><title> 566Version 1.1.5 567</title> 568 <itemizedlist spacing=compact> 569 <listitem> 570 <para> 571 Disable some overly-verbose debugging code 572 </para> 573 </listitem> 574 <listitem> 575 <para> 576 Remove unnecessary sound locks 577 </para> 578 </listitem> 579 <listitem> 580 <para> 581 Fix some ioctls for better time resolution 582 </para> 583 </listitem> 584 <listitem> 585 <para> 586 Begin spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl 587 </para> 588 </listitem> 589 </itemizedlist> 590</sect1> 591 592<sect1 id="version114"><title> 593Version 1.1.4 594</title> 595 <itemizedlist spacing=compact> 596 <listitem> 597 <para> 598 Completed rewrite of driver. Eliminated SoundBlaster compatibility 599 completely, and now uses the much-faster scatter-gather DMA engine. 600 </para> 601 </listitem> 602 </itemizedlist> 603</sect1> 604 605 </chapter> 606 607 <chapter id="intfunctions"> 608 <title>Internal Functions</title> 609!Idrivers/sound/via82cxxx_audio.c 610 </chapter> 611 612</book> 613