AC'97 sound driver for VIA 8233 chip


1. Disclaimer of liabilities

   No warranties of any kind are made. In no event shall the author be liable
   for any damage resulting from use or misuse of this product, either direct
   or consequential.


2. Quick start

   This driver  supports   sound    playback  and recording  with     the VIA
   Technologies  8233-based AC'97 controller.  It is   intended as an interim
   successor for  the VIA  686A  driver currently available in  the 68MU*.ZIP
   packages at http://downloads.viaarena.com. It will be superseded by ALSA/2
   drivers.

   Features at a glance:

        * Supports VT8233 and VT8233C (VT8233A/VT8235 not confirmed)
        * Variable  playback/recording rate  of 8000...48000 Hz (if supported
          by the AC'97 codec)
        * Unified mixer configuration using IOCTL90 interface
        * Software effects library for Avance Logic ALC-201A.

   Prerequisite CSDs:

        * OS/2 Warp 4 or higher: none.
        * OS/2 Warp 3: XR_W017 (AC97DIAG.EXE will need at least XR_W032).
          XR_D001 recommended to update base device drivers.

   To install, run the MMPM/2  MINSTALL.EXE program from the  directory where
   you unpacked this archive.


3. Advanced configuration

   Several  mainboard  manufacturers install  low-end AC'97  chips that never
   produce acceptable sound (a common adverse effect  is 50-70Hz noise during
   playback). This is a hardware problem not addressed here.

   The three separate mechanisms for controlling sound volume are as follows:

        - MMPM/2 "Volume" object
        - VOL=... in MMPM2.INI
        - AC'97 configuration registers (see below for a discussion)

   By default, the 8233 driver initializes AC'97 with the highest volume/gain
   values, which  are adequate for properly made  AC'97 chips (such as Avance
   Logic ALC-201A on EPoX 8KHA+/8K3A motherboards). These volume settings may
   be adjusted downwards if necessary.  Special attention must  be paid to PC
   Speaker volume, which might require "silencing" in certain cases.

   Although  not recommended by VIA,  it is possible  to use passive speakers
   with certain AC'97  chips for the purpose of  signaling system events.  To
   achieve  acceptable volume,  edit     the \MMOS2\MMPM2.INI   file    after
   installation and replace  VOL=50  with VOL=100  under  the PARMSTRING  for
   [IBMAMPMIXVIA1601]. If you experience distorted sound after this, it means
   that the output level is too high.

   Finally, all the AC'97 standard settings, including master volume, channel
   volume,  gain, 3D stereo  enhancement, bass/treble effects, are accessible
   through standard IOCTL90 interface.  The use  of IOCTL90 mixer front-ends,
   such as LBMix by Lesha Bogdanow, is suggested to set these parameters. For
   a typical onboard VT8233, the following parameters will be adjustable:

        - Master volume
        - PCM OUT volume
        - PC Speaker volume (mapped to the "Mono IN" control)
        - Line IN volume
        - Recording gain
        - 3D stereo enhancement on/off (if supported by hardware)
        - Bass/treble (if supported by hardware)

   If  the  Avance  Logic  codec  is  present (the driver  detects  this), an
   extended feature set will be made available by means of software simulated
   effects, some of which comprise an extension of the IOCTL90:

        - Voice cancellation
        - Bass/treble
        - Pitch shift
        - Surround

   Tip: in LBMix, certain  effects are set  by  buttons which  bear the "Off"
   label. When  such a  button  is raised, the particular  effect (e.g. 3D or
   voice cancellation) is  turned ON; when a button  is depressed, the effect
   is turned OFF. For a  patch that  enables these  effects in LBMix, see the
   ALC201A directory.


4. Driver parameters

   The VIAUDD.SYS  driver for  8233  does  not normally need  any  additional
   command-line parameters.   However, there are  some settings  which may be
   helpful:

        /N:<name>       Symbolic device name for  binding with MMPM/2. This
                        is automatically selected by MINSTALL.EXE. Defaults
                        to "VIAUD1$".

        /B:<hex addr>   Override the base  I/O port address  if incorrectly
                        assumed from the PCI configuration. Usual locations
                        are 0E000h and 0D800h.

        /IRQ:<number>   Override the IRQ channel  if the PCI  configuration
                        was incorrect. Attempts to  reconfigure the card to
                        use  a  different IRQ. The  default IRQ  channel is
                        number 5.

        /NO_IRQ_SHARING Disable the IRQ sharing  mode. Normally, VIAUDD.SYS
                        automatically detects whether IRQ sharing is needed
                        and performs the necessary setup.

        /ALC|/!ALC      Override  ALC-201A  detection. Normally the  driver
                        detects the presence  of ALC-201A automatically and
                        performs the necessary setup; however, the presence
                        of codec may be  forced using /ALC or disabled with
                        /!ALC.

        /LFREQ|/AFREQ   /LFREQ, which  is  the default  for chip  revisions
                        >=0x30, uses a modified frequency  algorithm  known
                        from VIA drivers for Linux. /AFREQ, default for the
                        older  revisions, uses  the  officially  documented
                        algorithm known from ALSA driver. Use /LFREQ if the
                        sound  plays too  slowly; use /AFREQ if  the  sound
                        plays too fast or with interruptions.

        /VERBOSE        Verbose  output,  useful  for  troubleshooting   or
                        finding  out  the capabilities  of a specific AC'97
                        solution. Shows if any  step during  initialization
                        fails and makes a pause to let the user examine the
                        results.

        /QUIET          Quiet initialization - display no messages at all.

        /R:<xxx>        Configure Audio Codec '97 registers  manually. This
                        is  intended  for  advanced  users, as  the IOCTL90
                        mixer  interface  should   be  usually  enough  for
                        customization. The format of <xxx> is:

                        <register>=<value>,<register=value>,...
                        or
                        <register1>..<register2>=value,...

                        Refer to AC'97 specification for a list of register
                        values and their meanings.

                        Practical examples:

                        Enable the +20 dB microphone gain:
                           /R:0E=40

                        Enable simulated stereo (if supported):
                           /R:20=4000

                        Enable bass boost (if supported):
                           /R:20=1000


5. Troubleshooting suggestions

   When submitting problem  reports to the  author, please include the output
   from the enclosed diagnostic utility (AC97DIAG.EXE),  redirected to a file
   (e.g. ac97diag>report.txt). Note: the diagnostic utility requires XR_W032+
   and IOPL=YES in CONFIG.SYS.

   A debug version of the driver is included that reports various events to a
   debug  terminal via  communications  port (COM2 is  assumed  by default; a
   different port can  be specified with /DEBUG:<base  address>).  To use the
   debug   version, connect a   debug  terminal and  replace  VIAUDD.SYS with
   VIAUDDD.SYS in CONFIG.SYS. 


   Problem: the device driver does not install. 

   Solution: 

        1. Check that you have the integrated soundcard enabled in BIOS (in
           Award BIOS, it's also called the "auto" mode).
        2. Use a PCI sniffer utility  to verify  if you have a  device with
           manufacturer  ID 1106h (VIA  Technologies) and  device  ID 3059h
           (the 8233 integrated sound). The driver installs only for 3059h,
           if  you happen  to  have  a 3058h  device, be  sure  to  use the
           original 686A driver for it.
        3. Run RMVIEW (or "System Setup -> Hardware Manager" in OS/2 v 4.x)
           to  examine the  I/O port  and  IRQ level assigned  to soundcard
           for absence of conflicts. If conflicting IRQs were found, enable
           ACPI   configuration  in  BIOS   and  install  the  driver  with
           /IRQ_SHARING.


   Problem: the system hangs during boot when the driver is installed.

   Solution:

        1. Enable ACPI configuration in BIOS.
        2. If one can't afford (1), the other solution is to ensure absence
           of any devices that share the IRQ with AC'97, and to install the
           driver with /NO_IRQ_SHARING option.


   Problem: Warp 3 traps after the driver is installed.

   Solution: remove the  line containing  DEVICE=x:\MMOS2\AUDIOVDD.SYS from
   CONFIG.SYS (this would prevent MVDM from sharing the AC'97 but there are
   no drawbacks, considering that no DOS applications  are known to support
   VT8233 AC'97).


   Problem: the device driver installs but no sound is audible.

   Solution:

        1. Install the driver with /VERBOSE switch to watch its output. Pay
           particular attention to the IRQ and base  address it guesses (if
           there  is  pure  nonsense  like  I/O   port  0000h,  try  manual
           override).
        2. Write down the chip revision from the driver installation screen
           (e.g. "rev. 0x40" - in case  of VT8233A). Contact the  author if
           your chip is not revision 0x30.
        3. Examine the conflicts in RMVIEW/Hardware Manager (see above).
        4. Verify  the  IOCTL90  mixer  setup - no output  channel must  be
           muted.
        5. (Advanced) Install debug kernel and  intercept _InterruptHandler
           in  VIAUDD.SYS  (Ctrl+C, then  enter "g _InterruptHandler"). Try
           some playback and report if the interrupt  handler is reached at
           least once.


   Problem: crackling noises during playback.

   Solution:

        1. Try decreasing the output volume  of MMPM/2 and the AC'97 volume
           registers  (in AC'97, the registers  control the attenuation, so
           higher values mean lower volume).
        2. Make sure  that your AC'97 chip  is capable  of playback  at the
           given frequency, bit count and number of channels.
        3. If  the  ALC-201A  software  library  is  used,  there  might be
           insufficient CPU power to apply postprocessing at interrupt time
           (try disabling the ALC-201A support with /!ALC).


   Problem: incorrect playback frequency.

   Solution:

        1. Run with /VERBOSE option to see if  the driver indicates support
           for variable rate  adjustment. If it does not, then your card is
           only capable of playing sounds at 48 KHz.
        2. Install the driver with the /LFREQ option.


   Problem: no sound in DOS or Win-OS/2 sessions.

   Solution: for   Win-OS/2,   install  the generic  Win-OS/2   sound  driver
   (http://home.wanadoo.nl/~rwklein/genmenu.htm).   For   DOS,  there  are no
   known applications with 8233  AC'97 support.  Therefore, this  problem may
   only    be   solved    in   hardware    (through   installation    of    a
   SoundBlaster-compatible card) or  with special software (e.g.  the Virtual
   PC commercial product from  Connectix/Innotek). As a side-note: the driver
   causes no known problems with Virtual PC.


6. Compatibility

   VIA 8233 is different   from 686A in that it   no longer provides the   FM
   synthesis    (required     for   MIDI)   and   SoundBlaster  compatibility
   options.  Besides, it is not fully  compliant to  the AC'97 specifications
   due   to  a specific variable  rate   adjustment configuration. The driver
   carries out the  workarounds necessary to deal with deviations from AC'97,
   however to  enable MIDI, the software MIDI  solutions must  be used - e.g.
   the TiMidity MCD freeware product, which also takes care about integration
   into MMPM/2.

   The current release of the driver does not  support configuration by means
   of a VSD settings page.   Mixer settings may  be adjusted with any IOCTL90
   front-end, such as LBMix.   If necessary, advanced AC'97 configuration may
   still be carried out with the /R: switch.

   It is suggested that you set up your system for ACPI configuration (unless
   there are  drivers that require explicit IRQ  allocation). This solves the
   most    common IRQ sharing conflicts that    prevent the  8233 driver from
   working properly.


7. Revision history

   Tip: in OS/2  v 4.0+, use the Hardware  Manager to examine the revision of
   your driver.

        1.2   [25/01/2002]  Spin-off from 17/10/2001 VT82C686A driver.

        1.3   [05/03/2002]  GA version - added AC'97 configuration options.

        1.4   [07/03/2002]  Added IOCTL90 V1 interface, improved  the AC'97
                            startup initialization.

        1.5   [17/03/2002]  Added the /EXTINIT switch.

        1.6   [16/04/2002]  IRQ code reworked towards ACPI compliance.

        1.7   [23/04/2002]  Implemented   LFREQ  auto-detection   and  base
                            support  for AC'97  extensions in  Avance Logic
                            ALC-201A.

        2.0   [01/07/2002]  Fixed  looping at some  WAV files when playback
                            ends. Implemented  the software effects library
                            for ALC-201A. /IRQ_SHARING is  now  the default
                            (changed to /NO_IRQ_SHARING to allow override).
                            Removed the /EXTINIT switch.

        2.1   [03/07/2002]  Removed  the  /SB  switch.  Added   preliminary
                            support for VT8233A (including KT333 boards).


8. Credits

   The object code included within this package is based on the existing OS/2
   drivers for  VIA 82C686 and  the  ALC-201A driver. This package  uses  the
   sample code of IBM Developer Connection Device Driver Kit for OS/2.

   (C) 1997-2001, VIA Technologies Inc.
   (C) 1999-2001, Realtek Semiconductor Corp.
   (C) 1993-1995, International Business Machines, Inc.
   (C) 1991-1995, Media Vision Corp.
   (C) 1990-1993, Voyetra Technologies.


9. Contacting the author

   The author can be contacted  at <andrew_belov@newmail.ru>. When submitting
   a problem report, include the exact chipset revision and type of mainboard
   you are using, the version of OS/2 and RMVIEW information.

   You may also request the source for certain  files that have been included
   in this package in their OBJ form. Please be warned that  the missing code
   bears  the  aforementioned  copyrights  and is  subject of IBM OS/2 Device
   Driver Kit license  which prevents  it from being  used for  purpose other
   than the development of OS/2 device drivers.

   $Id: readme.txt,v 1.23 2002/07/02 22:58:33 root Exp $
