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