AC'97 sound driver for VIA 8233/8235 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/8235-based  AC'97  controllers.  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 is superseded  by
   an ALSA/2 driver currently being tested.

   Features at a glance:

        * Supports VT8233, VT8233C, VT8233A and VT8235.
        * 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.

   The  driver comes in two archives. The  first, 823XAC97.ZIP, contains  the
   required  files  for installing  the driver  in MMPM/2.  The supplementary
   archive, usually available as 823X_ADD.ZIP, provides additional components
   that are  not mandatory: startup  sound driver, diagnostic tools, patches,
   source code and programming samples, etc.


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 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 VT823x, 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 in supplementary archive.


4. Driver parameters

   The VIAUDD.SYS driver for 8233/8235  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$".

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

        /!OEM           Prevent any special setup for AC'97 codec ICs. This
                        parameter disables  any vendor-specific  setup done
                        by the driver.

        /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 (/!ALC is a synonym for /!OEM).

        /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  diagnostic utility (AC97DIAG.EXE) enclosed in  the supplementary
   archive. Run  it  with redirection  to a  file (e.g. ac97diag>report.txt).
   Note: the diagnostic utility requires XR_W032+ and IOPL=YES in CONFIG.SYS.

   The supplementary archive  also contains a debug version of the driver. It
   reports various events to a debug terminal via  communications  port (COM2
   is  assumed  by   default;  a   different  port  may   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 823x 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.


   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
   VIA AC'97).


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

   Solution:

        1. Examine the conflicts in RMVIEW/Hardware Manager (see above).
        2. If you are using an IOCTL90 mixer, verify  its setup - no output
           channel must be muted.
        3. Install the driver with /VERBOSE switch to watch  its output. If
           any warning messages were displayed, or the IRQ and port address
           seem to be invalid, contact the author.
        4. Examine MMPM/2 setup. VT8233 audio driver should be the "default
           Waveaudio device". If you were  installing  the driver on top of
           a  previously  installed driver, pay attention to  making VT8233
           driver the default one and cleaning up your MMPM/2 configuration
           accordingly.


   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 823x  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/8235  are different from 686A in  that they no longer provide the
   FM synthesis (required  for MIDI) and SoundBlaster compatibility  options.
   Besides,   earlier revisions   are    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.  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  823x 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).

        2.2   [20/08/2002]  Removed the /IRQ and /B  switches. Improvements
                            for VT8233A and VT8235. Implemented hibernation
                            support. Split  the  distribution  package into
                            main and supplementary archive.

        2.3   [09/10/2002]  Fixed several compatibility  issues with P4x266
                            chipsets.  Improved  the  setup  algorithm  for
                            VT1612A codec. Implemented on-line  diagnostics
                            collection for AC97DIAG. Added the /!OEM switch
                            and turned /!ALC into a synonym for /!OEM.


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>.   Prior   to
   submitting a problem report, please refer to section  5 to ensure you have
   tried out the common  workarounds  and collected the necessary  diagnostic
   information (using AC97DIAG.EXE).

   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.27 2002/10/08 23:40:15 root Exp $
