AC'97 sound driver for VIA 8233/8235/8237 chips


1. Introduction

1.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.

   This driver  is  released to  public domain; any  copyright claims  of its
   authors are hereby waived.

1.2. End-of-life notice

   The  development of  the   present driver has  been   ceased.   Unless any
   specific  problems or   limitations  arise, the  ALSA/2  (UniAudio) family
   should be considered as a long-term replacement. The ALSA/2 package can be
   downloaded at: 

                        http://os2.kiev.ua/en/uniaud.php

1.3. Overview

   The present driver supports sound playback and  recording with Audio Codec
   '97 (AC'97) solutions built around  VIA 823x controllers.  It was intended
   as an interim successor for the VIA 686A driver currently available in the
   68MU*.ZIP packages at  http://downloads.viaarena.com and  is superseded by
   the ALSA/2 unified solution as mentioned above.

   Features at a glance:

        * Supports VT8233, VT8233C, VT8233A, VT8235 and VT8237
        * Variable playback rate of 4000...48000 Hz.
        * Unified mixer configuration using IOCTL90 interface.
        * Software effects library for Avance Logic/Realtek AC'97 chips.
        * Experimental software-handled multistream mode

   Due to  unavailability of programming documentation, VT8235 and VT8237 are
   handled in the same  way as VT8233A and may  manifest several limitations.
   Envy24 and VT8239 will not be supported by the present driver.


2. Installation

   Prerequisite CSDs:

        * OS/2 Warp 4 or higher: none.
        * OS/2 Warp 3: XR_W022 (AC97DIAG.EXE will  need at  least XR_W032).
          XR_D001 recommended to update base device drivers.
        * Older versions of OS/2: version 1.7 of this driver was compatible
          with OS/2 v 2.1  and pre-XR_W022  Warp 3. It did not  include the
          support for  VT8233A/8235/8237; only VT8233/8233C were supported.
          That  particular  version  is  no  longer  available  but may  be
          requested   via  e-mail  from   the  author  (see   "Credits  and
          Maintenance").

   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.

2.1. Upgrading

   If  you have previously installed  an earlier  version  of this driver, to
   update it you can just copy VIAUDD.SYS from this archive over the previous
   installation (typically, it is in  \MMOS2 of  the startup drive).  Certain
   parameters might have been changed, be sure to review them against section
   4 of this document.


3. Advanced configuration

3.1. Low-end solutions

   Several mainboard manufacturers install low-end AC'97 chips and pay little
   attention   to  protecting    the    sensitive  analog   circuits     from
   interference. The common adverse effects are 50-70Hz noise during playback
   as  well as  crackle  caused by  mouse movement and  disk drive operation.
   This   is a hardware   problem  not  discussed  in  the  present document.
   Sometimes this issue may  be mitigated by muting  all unused analog inputs
   (such as LINE IN, CD, AUX...)

3.2. The software upsampling algorithm

   A problem  related to  the "value" codec  ICs  is a 48 kHz  fixed sampling
   rate.   This issue also arises when  the multistream mode is employed (see
   section 3.5). Most applications still rely on the  soundcard being able to
   process data at 8/11.025/16/22.05/24/32/44.1 kHz.

   If VIAUDD.SYS discovers it is  impossible to use hardware for  resampling,
   it will make efforts  to dynamically convert  all output to 48 kHz  during
   playback (recording rate will be limited to 48 kHz in this case).

   The conversion algorithm presently used by the driver is far from perfect,
   hence the quality of output may be quite  low at frequencies other than 48
   kHz.  The algorithm is nevertheless  adjustable (see "/INTERP:" in section
   4) and with some knowledge it can be adapted to a particular environment.

   Some multimedia applications may have an  option to perform the conversion
   to 48 kHz on their  own - enabling this  option might improve the playback
   quality (consult the corresponding documentation).

3.3. Volume controls

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

        - MMPM/2 "Volume" object (or "master" AC'97 register)
        - Current stream volume
        - AC'97 configuration registers (see below for a discussion)

   This version   of driver initializes  the   AC'97 registers  with "normal"
   volume/gain levels,  which are adequate for most  AC'97  chips, and may be
   readjusted upwards if necessary. 

   Although not  endorsed by mainboard  manufacturers, 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
   making this change, 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 (see comments below)
        - Line IN volume
        - Recording gain
        - 3D stereo enhancement on/off (if supported by hardware)
        - Bass/treble (if supported by hardware)

   For PC speaker output to be heard over  AC'97 (and for "PC Speaker" volume
   control to have any  effect), there must  be a physical connection from PC
   speaker  outputs to  AC'97   analog inputs.   Most mainboards provide  the
   necessary wiring (typically routed to  the "Mono IN" control), otherwise a
   manual connection to  a free 4-pin   onboard inlet is  required.  See your
   mainboard manual for connector diagrams.

3.4. Avance Logic extensions

   If the Avance Logic or Realtek 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.

3.5. Multistream mode

   The /MULTISTREAM:  parameter   (see section 4)  enables  the  experimental
   multistream mode in  which the driver can  handle several playback streams
   concurrently, mixing  them  in  real time.   While one  application  (e.g.
   multimedia player) is engaged  in audio playback,  another one (e.g. alarm
   clock) may sound some event without interrupting the former.

   Not  only is  the  multistream mode experimental,  it   is also marginally
   compatible and relentlessly CPU-intensive.  It  requires all output to  be
   upsampled to 48 kHz (think of /!VRA and concomitant quality losses) and it
   expects applications to supply data  promptly as there are less allowances
   for  delay than in  single-stream mode. Moreover, certain applications may
   still prevent others from acccessing the audio device. 

   For MMPM/2 to be fully aware of the driver's multistream capabilities, the
   MMPM2.INI file should be revised.  Locate the section [IBMWAVEVIA1601] and
   update the following lines:

   RESOURCEUNITS=33
   RESOURCECLASSES=2,32,1

   Then insert the following line below those two:

   VALIDCOMBINATIONS=1,2,2,1

   Repeat these steps for a section that reads [IBMAMPMIXVIA1601].

   That  will keep MMPM/2  from   assuming the card  is in   use while it  is
   actually not.  The  example is given for  32 streams but is applicable for
   most of practical setups.


4. Driver parameters

   Normally,  VIAUDD.SYS  will not  require any additional parameters  on its
   command line. However, there are some  settings which  may be  helpful for
   advanced customization purposes.

        /V[ERBOSE]      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.

        /Q[UIET]        Quiet initialization - display no messages at all.

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

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

        /DIRECT         Enable  the  Direct  Audio  interface. May  enhance
                        performance with Odin-based applications.

        /!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-xxx  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).

        /!VRA|/LFREQ|/AFREQ
                        These  options override  the way how the output  is
                        converted to 48 kHz  frequency demanded  by  codec.
                        Normally   the   driver   chooses  the   best   way
                        automatically.

                     -  /!VRA forces the driver to convert its output to 48
                        kHz in software,  bypassing the option to use AC'97
                        or chipset features.
                     -  /LFREQ,  which  is  the  default for chip revisions
                        >=0x30, uses  a modified  frequency algorithm known
                        from VIA drivers for Linux.
                     -  /AFREQ,  default for any  older chipset  revisions,
                        uses the officially documented algorithm known from
                        ALSA drivers.  Use  /LFREQ if the sound  plays  too
                        slowly; use /AFREQ if  the sound plays too  fast or
                        with interruptions.

        /!PCMVOL        Control the PCM volume (wave output volume) through
                        software. Certain  low-end  codecs, such as C-Media
                        CMI9739A, may require  this. The driver attempts to
                        set this mode automatically for known codecs.

        /ALTLINE        Bind  the mixer  to  an "alternate"  master  volume
                        control register. Use if the master  volume control
                        in MMPM/2 has no effect on the actual volume.

        /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:

                        <register1>=<value1>,<register2>=<value2>,...
                        or
                        <register1>..<register2>=value,...

                        ".." in  the last  example  stands for  a  register
                        range.

                        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

        /INTERP:<n>[:<x>[:<s>[:<f>[<w>]]]]
                        When  software  resampling  is  forced  by /!VRA or
                        demanded  by codec, this parameter  will  configure
                        the magnitude of interpolation <n> and, optionally,
                        descaling  factor <x>, shift  factor <s> and filter
                        magnitude <f>. Generally,  it trades  speed  versus
                        quality  of  the   resampling.  The  defaults   are
                        /INTERP:1:100:0:9t.

                     -  <n> specifies the magnitude in the range of 0 to 7,
                        i.e. the number of points  considered when plotting
                        a curve across them. Note the actual sense of <n>:
                        0 (or 1) = zero-order, discontinuous levels
                               2 = linear, continuous zigzag line
                               3 = quadratic, smooth curve with inflections
                               4 = cubic, inflection points suppressed
                     -  <x> sets descaling relative to the  original signal
                        level (100), possible  values  are 1 to 200.  Lower
                        values are helpful to  avoid  hiss - at the cost of
                        reduced output volume.
                     -  <s> allows to choose the midpoint  where the output
                        value  is  taken.  Valid  values  are 0  to  <n-1>,
                        inclusively. By  default, a  point adjacent to  the
                        center of the interpolated region is selected, that
                        is, for  magnitude  of  3,  it would  be (3/2)=1.5,
                        rounded to 2. For <n> of 0, <s> is always 0.
                     -  <f> sets an attenuation band for low-pass filtering
                        as a power of two for number of points in the  Fast
                        Fourier Transform. The default is  thus 512  points
                        (2^9). The range  of values is 2 ... 11, and 0 will
                        disable  the filtering.  The CPU  utilization grows
                        with <f>, but slower in the higher values. The cost
                        of going from 8 to 9 is about 19%, while changing 9
                        to 10 increases the overhead only by 16.5%.
                     -  <w> optionally defines  a postprocessing window. It
                        helps to avoid clicks between the resampled frames.
                        It is only  effective  for non-zero  values of <f>.
                        The following windows are available:
                          0  No windowing
                          d  Triangular window
                          m  Hamming window
                          n  Hanning window
                          s  Sine rise/cosine decline
                          t  Trapezoid window (default)
                          w  Welch window
                        For larger values of <f>, a <w> of 's' or 't' would
                        be most practical.

        /MULTISTREAM:<n>[:<l>[:<t>]]
                        Enable the experimental multistream mode.

                        <n> is used to define the maximum number of streams
                        in the  system. Values from  1 to  32 are  allowed,
                        typically 4 to 8 should  be adequate (larger values
                        take more memory - ca. 5M for 32 streams - as  well
                        as impose certain CPU overhead).

                        <l> defines the  lead time (in milliseconds)  - the
                        time required to process  the sound data inside the
                        driver.  This  parameter depends on CPU performance
                        and resampling settings. The default is 85 ms.

                        <t>  defines the   maximum   "starvation" time  (in
                        milliseconds)  - the duration  for  which the AC'97
                        device is still  fed with silence after the  actual
                        data  transfer has been  stopped.  This compensates
                        the lagging of the sound  effect engine and  allows
                        the transfer  to  resume faster,   if required. The
                        default is 1250 ms.

        /BUF:<s>=<v>[:<s>=<v>[:...]]
                        Fine-tune the buffering. Allows to set  the maximum
                        size for individual  buffers. Note the defaults are
                        almost  universally acceptable, moreover, there  is
                        an algorithm for grinding out the "advisory" buffer
                        size which may conceal any effect of customization.

                        The  following  string/value  (<s>=<v>)  pairs  are
                        allowed:

                     -  L=<number> specifies the number  of logical buffers
                        in a  segmented chunk of S/G DMA (e.g. L=4), values
                        from 3 to 32 can be used.

                     -  LS=<bytes>  specifies the  logical  (MMPM/2) buffer
                        size  after  upsampling.  The  physical  (S/G  DMA)
                        semibuffers are always set as close as possible to
                        this  value (e.g. LS=32768 will keep  the resampled
                        buffers  close  to,  but  not  exceeding, 32K). The
                        range is 2048 to 32768.

                     -  PPL=<number> sets  the  number of  physical buffers
                        per a single logical buffer in multistream mode. In
                        single-stream mode it is fixed at 1. The range is 1
                        to 84.

                     -  P=<number>  specifies the  number  of physical (S/G
                        DMA)  buffers in multistream mode. In single-stream
                        mode, physical buffers  are always  scaled relative 
                        to the logical buffers. The range is 3 to 254.

                     -  PS=<bytes>  specifies  the  physical buffer size in
                        bytes  for  multistream mode. The  range is 2048 to
                        32768.

                        Since the parameters  are related, there is no need
                        to calculate all of them manually. For example, the
                        parameter "/BUF:L=8:P=32:LS=32768" will imply  four
                        physical buffers per logical buffer whose size then
                        becomes 8192 bytes.

                        Tip: the  "waterline"  statistics in  the  AC97DIAG
                        output can assist you in tuning the buffer size.


5. Troubleshooting suggestions

5.1. Using AC97DIAG

   When  working  out   various  problems, both  end-users  and  source  code
   maintainers  may  find  the  AC97DIAG.EXE diagnostics  utility  useful for
   getting  snapshots    of  the situation.    The    utility  comes  in  the
   supplementary   archive.  It can  be run  with a  redirection to some file
   (e.g.    ac97diag>report.txt).  Note:   the   diagnostic utility  requires
   XR_W032+ and IOPL=YES in CONFIG.SYS.

5.2. Common problems

   Problem: the device driver does not install. 

   Solution: 

        1. Check that you have the integrated soundcard enabled in BIOS (in
           Award BIOS, it is sometimes 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, try to
           toggle the PnP/ACPI autoconfiguration options in BIOS.


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

   Solution:

        1. Toggle  the  PnP/ACPI  configuration  options  in BIOS (e.g. try
           to  dismiss  any  reserved IRQs  and  enable  the  automatic IRQ
           assignment).
        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 /!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, the driver has to be debugged.
        4. Examine MMPM/2 setup. VT823x 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 VT823x
           driver the default one and cleaning up your MMPM/2 configuration
           accordingly.
        4. Ensure  that "IBMWAVE1601" is  present  in the "Waveaudio"  list
           under "[Drivers]" in MMPM2.INI.
        5. If it is absent from MMPM2.INI, try the following steps:
           - Re-run MINSTALL and install the driver as usual.
           - Prior to shutdown, back up the modified MMPM2.INI.
           - Reboot into command prompt  or "Maintenance Desktop" to obtain
             complete access to your system while avoiding MMPM/2 startup.
           - Copy the backup copy of MMPM2.INI back into MMPM2.INI.
           - Reboot.
           This  fixes  a  rarely occuring  error (reported by  users) with
           MMPM2.INI getting overwritten by an old copy.


   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 Avance Logic  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: 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.


   Problem: incorrect playback frequency.

   Solution:

        1. Install the driver with the /LFREQ option.
        2. Force software resampling by means of the /!VRA parameter.


   Problem: the master volume slider does not affect the volume.

   Solution: append the VIAUDD.SYS command line in CONFIG.SYS with "/ALTLINE"
   (without quotes) and reboot the system.


5.3. Online debugging

   The supplementary archive also contains a debug  version of the driver. It
   reports various  events to a  debug  terminal via RS-232 ports. The output
   is enabled with the parameter /DEBUG:<address>[:<channels>], where:

        <address>       Stands for the base  address of the  COM port. In a
                        typical setup with  the debug terminal connected to
                        COM2, <address> will be 2F8 (hex).

        <channels>      Lists the debug  channels to watch.  The default is
                        to  pass all   debug output  which  may impair  the
                        real-time    performance.  A  string   of   letters
                        (case-sensitive)  can  then  be  supplied to filter
                        only a part of the data:

                     -  "c" enables Configuration-related output
                     -  "D" enables Direct Audio debug logging
                     -  "e"   enables   Effect-related   output   (whatever
                        concerns the application of software effects)
                     -  "i" enables brief Interrupt-time statistics
                     -  "I" enables additional  Interrupt-time   statistics
                        (the  debug  traffic  may  introduce  audible  lags
                        during playback)
                     -  "s" enables  Stream-related output (the  life-cycle
                        and temporal coordinates of MMPM/2 streams)
                     -  "x" enables  eXtraordinary  output  (any conditions
                        not taken into the design).

   Practical examples:

   /DEBUG:2F8:x         draws the attention to abnormal situations only
   /DEBUG:2F8:sex       is the right setup for in-depth investigation
   /DEBUG:2F8:Dsx       when a Direct Audio-enabled application fails
   /DEBUG:2F8:siIx      should only be used to debug the S/G DMA engine

   To  perform debugging,  install  the OS/2  debug   kernel, connect a debug
   terminal and replace VIAUDD.SYS  with VIAUDDD.SYS  in CONFIG.SYS. A faster
   baudrate (19200  or more) is recommended to handle  large volumes of debug
   information while retaining the real-time operation.

   The debug driver may also stop  execution at  certain assertion  points to
   allow you to investigate situations which look admittedly erroneous.


6. Compatibility

   VT8233/8235 are different from VT82C686 in that they no longer provide the
   FM synthesis  (required for MIDI)  and SoundBlaster compatibility options.
   Earlier revisions of VT8233 presumably take over some AC'97 functionality,
   e.g.  a VRA-capable codec  was not required  before  VT8233A. In terms  of
   AC'97 support, VT8237 seems to be an evolutionary successor to VT8235.

   For MIDI output on  AC'97,  software MIDI  solutions have to  be employed,
   such as 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 PnP/ACPI  configuration
   (unless there  are any drivers  requiring explicit IRQ  allocation).  This
   solves the most common IRQ sharing conflicts  that prevent the 823x driver
   from  working properly. Nevertheless, IRQ  assignment  has to be completed
   before the installation of  this  driver (certain ACPI configurations  may
   defer the IRQ setup to operating system mechanisms).


7. Development information

   This  section  is intended to supplement  the source  code comments. Prior
   experience of the readers with OS/2 DD development is implied.

7.1. Code organization

   The driver is made up of two  pieces, 16-bit "physics" and 32-bit "maths",
   located in the "8233ac97" and "softsnd" source subtrees, correspondingly.

   The 32-bit part is responsible for audio  format (8->16 bits) and sampling
   rate conversion, application of  software effects  and output into the S/G
   DMA (scatter-gather direct memory access) memory  area. It has quite a few
   entry points with all necessary wrappers to accept 16-bit calls.

   The 16-bit part, complemented by code  from DDK\base\src\dev\common, makes
   up the core of the driver.

   Directory names are important - the driver should  be added to a \DDK tree
   containing  the   IBM  OS/2  Device  Driver  Kit  with  the  MMPM/2  build
   environment.

   In order to compile the driver, one has to build the 32-bit library first,
   then   run  "nmake  COPYMS=1"  for the   16-bit complementary   library in
   DDK\base\src\dev\common (yielding DDK\base\lib\libpcidr.lib),   then   get
   into the "8233ac97" directory to compile the rest of code. 32-bit portions
   may be built  with any C compiler  aware  of SS!=DS  and "long  long" data
   type, presently the choice is:

        * OpenWatcom v 1.x
        * GCC/EMX v 3.2.1-20030306
        * IBM VisualAge C++ v 3.65
        * Metaware High C/C++ v 3.2

   The 16-bit code is handled by MS C v 6.0 (from DDK) and MASM/ALP.

7.2. Understanding the S/G DMA

   Most PCI I/O devices (including  the AC'97 controllers) employ the concept
   of Scatter-Gather DMA.  The   producer "scatters" the  data across  a  few
   areas  in  memory,   the  consumer  "gathers"  them in  exactly   the same
   order. Generally there are no  limitations as to the  size and location of
   these RAM buffers.  S/G  DMA can be viewed  as an evolution of i8259 (ISA)
   DMA, only with a greater degree  of freedom provided  by the PCI busmaster
   architecture.

   VT823x can handle up  to 254 distinct  buffers for playback and recording,
   chained together to form a single circular buffer. The recording mode only
   uses four  fixed-size buffers whereas  the  playback mode relies  on  more
   extensive capabilities  of S/G DMA.  It is  worth remembering the playback
   can be put in either  of two separate  submodes (take a look on  8233DMA.C
   for better understanding). 

   The  single-stream playback assigns buffers  to each chunk  of data we get
   from  MMPM/2 - soon after  a portion of data  arrives, a dedicated S/G DMA
   buffer is formed for it and its size is  adjusted accordingly. Essentially
   there  is a  circular chain  of  large "logical"   buffers.  The  S/G  DMA
   transfer (and hence  the playback) ceases as soon  as  it finishes playing
   the recently added buffer. 

   Multistream mode is entirely different: it exploits  a finer division into
   many small buffers  which serve only as points  where IRQs may occur.  The
   data arriving from MMPM/2 is not aligned with  these. One direct corollary
   is that  MMPM/2 should   always send data   in larger  portions  than this
   smallest "physical" buffer in order for IRQs to come in time.

   The data transfers  compete  to "overtake" the  running S/G DMA  counter -
   new  streams join the transfer  either at the top  of the first buffer (if
   the S/G DMA is  not running by this  time) or some  kilobytes ahead of the
   pointer (if it is already  running).  Thus the  S/G DMA pointer is loosely
   related  to  MMPM/2 buffer boundaries.  Rather  than  to cease immediately
   upon the exhaustion of data, the  S/G DMA continues to  run until the last
   running  stream had  no  data for a  certain  period of  time ("starvation
   term") during which silence is still pumped through a sequence of filters.


8. Revision history

   Tip: in OS/2  v 4.0+, use the Hardware  Manager to examine the revision of
   your  driver.  The driver version is  stated on the "Description" line for
   the corresponding   resource  entry  (the   "Version" field  reflects  the
   interface version).

        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 compatiblity with PnP
                            and ACPI autoconfiguration.

        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.

        3.0   [11/05/2003]  Added experimental upsampling to 48kHz. Changed
                            the  VRA  detection logic. Reduced  the default
                            channel volume/gain levels.

        3.1   [25/06/2003]  Improved  the  buffering  algorithm. Fixed  the
                            wave volume  separation  for IOCtl90 and stream
                            settings.

        3.2   [13/07/2003]  Fixed pause/resume functionality (regression in
                            v 3.1).

        3.3   [07/10/2003]  Workaround  for  faltering playback  in IBM JRE
                            v 1.1.x (regression  from  v 3.0). Improved the
                            upsampling implementation.

        3.9   [23/07/2004]  Minor corrections in  codec detection routines.
                            Fixed the recording source selection. Added the
                            /ALTLINE  parameter. Redesigned  the resampling
                            code - previous JRE workaround is now obsolete.
                            Further  improved  the   upsampling  precision.
                            Removed all object-code-only modules. Added the
                            /V  and  /Q  shortcut  parameters  and  changed
                            "/NO_IRQ_SHARING"   to    "/!IRQ_SHARING"   for
                            constistency.  Fixed  a  trap  when  upsampling
                            irregular frequencies (e.g. 47777 or 47999 Hz).
                            Fixed interrupting playback under the Odin DART
                            wrappers (regression from v 3.0).

        4.0   [03/09/2004]  Some streams might start in silence (regression
                            in v 3.9). Documented the /MULTISTREAM: option.
                            Added  Direct Audio support. Fixed  clicks when
                            resampling (regression in v 3.9).

        4.1   [11/09/2004]  Implemented  initialization and general support
                            for AD198x and CMI-973x  codecs. Added /!PCMVOL
                            to control the output volume in software.

        4.2   [28/12/2004]  Implemented  AD1888 initialization. Changed the
                            /R   parameter   processing  to   program   the
                            registers  in  the   same  order  as  they  are
                            specified on command line.

        4.3   [30/12/2004]  /ALC was inoperable (regression from v 4.1).


9. Credits and maintenance

   This driver comprises  a redesign of the  older VIA 82C686 driver for OS/2
   and Realtek ALC-201A driver for Windows NT.

   Andrew Belov <andrew_belov@newmail.ru> carried out the development work on
   the way from 1.2 to  4.3.  Many OS/2  users  were helpful in testing  this
   software over the years,  contributing their time to improve compatibility
   with poorly-documented hardware.

   The driver is   presently  unmaintained.  Please observe the   end-of-life
   conditions and consider alternate solutions  before you submit bug reports
   to the author. In general, source code patches  are now the preferred form
   of bug reports.

   $Id: readme.txt,v 1.63 2004/12/30 16:33:05 root Exp $
