                Crystal Semiconductor Corporation
                ---------------------------------


READ.ME - OS/2 Crystal Audio Device Driver Installation
--------------------------------------------------------------------------
This file contains information on how to install the Crystal Semiconductor
Corporation OS/2 Audio Device drivers.

In addition to Crystal Audio driver installation, this diskette includes
the IBM OPL3/FM MIDI synthesis device driver.

The following topics are covered in this READ.ME file:
1)  Installing on top of previous installations
2)  De-Installation of Sound Blaster Drivers
3)  System Requirements
4)  Files List for Crystal Audio Install Disk
5)  Crystal Audio for OS/2 Installation Procedure
6)  Device Driver Command Line Options
7)  Notes on Command Line Options
8)  Using Audio in DOS and Win-OS/2 Sessions
9)  Audio Concurrency Issues - OS/2, DOS, Win-OS/2
10) Plug and Play System Issues
11) Mixer Issues
12) MIDI Synthsis
13) Web Site
14) Special notes on upgrading from driver version 1.xx to 2.xx.
15) Problems/Questions


1)  Installing on top of previous installations
-------------------------------------------------------------------------------
This installation supports installation over all previous installations of
Crystal Audio device drivers as well as over-installation of IBM's
OPL-3 device driver.

No de-install is necessary prior to executing the OS/2 Multimedia
installation program, minstall.exe.

If you already have a non-Crystal device driver set installed,
it may be necessary to de-install those drivers before installing
Crystal Semiconductor audio device drivers.


2) De-Installation of Sound Blaster Drivers
--------------------------------------------
With some Crystal Semiconductor parts, when installing OS/2 Merlin,
the system will incorrectly identify a Sound Blaster device - resulting
in erroneous installation of Creative Technologies Sound Blaster OS/2
device drivers.   This error occurs because most Crystal Semiconductor
CODECs include hardware support for Sound Blaster compatibility for DOS
game execution.

The Crystal Semiconductor installation (on this diskette) searches for
previous installations of Crystal Semiconductor drivers and
automatically de-installs them as part of the installation process.
It does not de-install Sound Blaster device drivers.

If your system presently has Sound Blaster OS/2 device drivers installed
and you do not have a Sound Blaster device installed, then you should
de-install the Sound Blaster OS/2 drivers prior to running this installation.

The de-installation of the Sound Blaster OS/2 device drivers requires
the following steps:

a) ERASE \MMOS2 and all subdirectories (this removes OS/2 multimedia support)
   Some files won't delete, this is okay.
b) Use OS/2 selective install to re-install OS/2 multimedia support.
   It will auto-detect the wrong device.  You should override
   the auto-detection to remove the Sound Blaster device driver.
   When correct, the installation panel will have no audio devices listed.
c) Complete selective installation and reboot
d) You are now prepared to use this diskette to install Crystal drivers.


3)  System Requirements
-------------------------------------------------------------------------------

This installation and device drivers work on the following OS/2 systems:
    OS/2 Warp 3.0            ( Warp - Red box )
    OS/2 Warp 3.0 Fullpack   ( Warp - Blue box )
    OS/2 Warp Connect        ( Warp - Blue box )
    OS/2 Warp 4.0            ( Merlin )

In the above "Bluebox" and "Redbox" refer literally to the color of the
retail OS/2 box.

    Red box => "Warp for Windows".
               Uses previously installed Windows 3.1 binaries for WinOS2.

    Blue box => "Full pack".
               Windows 3.1 binaries are shipped with OS/2.


4)  File List for Crystal Audio Install Disk
-------------------------------------------------------------------------------

List of all files (sorted by name)
----------------------------------
    AMPMXMCD.DLL - IBM MMOS2 Amp Mixer update, installed Warp 3 if fixpack <26
    AMPMXMCD.F26 - IBM MMOS2 Amp Mixer update, installed Warp 3 if fixpack =26
    AUDIOIF.DLL  - IBM MMOS2 Audio VSD update, installed Warp 3 if fixpack <26
    AUDIOIF.F26  - IBM MMOS2 Audio VSD update, installed Warp 3 if fixpack =26
    CLOCK01.SYS  - IBM High res timer driver/clock, installed Warp 3 only
    CLOCK02.SYS  - IBM High res timer driver/clock, installed Warp 3 only
    CONTROL.SCR  - Installation control file
    CWBAUDI3.DRV - Crystal Windows 3.1 audio driver
    CWBAUDI3.INI - Crystal Windows 3.1 .INI file
    CWBFM.DRV    - Crystal Windows 3.1 FM driver
    CWADD.INI    - Crystal Windows 3.1 system.ini
    CWAUDIO.sys  - Crystal OS/2 Audio PDD/BASEDEV
    CARDINFO.DLL - Installation control resource DLL
    CWINST.DLL   - Crystal installation executable
    CWVAUDIO.SYS - Crystal OS/2 Audio VDD
    FILAUDFM.SCR - Installation control file, audio + FM installation
    FILAUDWT.SCR - Installation control file, audio + MPU-401 installation
    MIDIMAP.CFG  - Crystal Windows 3.1 FM MIDI map
    MIDIPLAY.ICO - Installation ICON for FM driver
    OPL3.SYS     - IBM OPL-3/FM OS/2 device driver
    OPL3RES.DLL  - Runtime capabilities for FM driver
    READ.ME      - This file
    TIMER0.SYS   - IBM High res timer driver/clock, installed on Warp only



Files listed by function:

Crystal OS/2 Audio driver
-------------------------
    CWAUDIO.SYS  - Crystal OS/2 Audio PDD
    CWVAUDIO.SYS - Crystal OS/2 Audio VDD

Crystal Windows 3.1 audio/fm driver
-----------------------------------
    CWBAUDI3.INI - Crystal Windows 3.1 .INI file     (installed on Merlin only)
    MIDIMAP.CFG  - Crystal Windows 3.1 FM MIDI map   (installed on Merlin only)
    CWBFM.DRV    - Crystal Windows 3.1 FM driver     (installed on Merlin only)
    CWBAUDI3.DRV - Crystal Windows 3.1 audio driver  (installed on Merlin only)
    CWADD.INI    - Crystal Windows 3.1 system.ini    (installed on Merlin only)

IBM OPL-3/FM OS/2 audio driver
------------------------------
    OPL3.SYS     - IBM OPL-3/FM OS/2 device driver
    OPL3RES.DLL  - Runtime capabilities for FM driver
    MIDIPLAY.ICO - Installation ICON for OPL-3 driver

Warp 3.0 OS Updates: (These are installed only on Warp 3.0 systems)
--------------------
    AMPMXMCD.DLL - IBM MMOS2 Amp Mixer update        (installed Warp 3.0 only)
    AUDIOIF.DLL  - IBM MMOS2 Audio VSD update (Dart) (installed Warp 3.0 only)
    CLOCK01.SYS  - IBM High res timer driver/clock   (installed Warp 3.0 only)
    CLOCK02.SYS  - IBM High res timer driver/clock   (installed Warp 3.0 only)
    TIMER0.SYS   - IBM High res timer driver/clock   (installed Warp 3.0 only)

Installation files
------------------
    CONTROL.SCR  - Installation control file         (read by minstall.exe)
    CTRAUDFM SCR - Installation control file         (copied to control.scr)
    CTRAUDWT SCR   Installation control file         (copied to control.scr)
    FILAUDFM.SCR - Installation control file         (copy list for FM inst)
    FILAUDWT.SCR - Installation control file         (copy list for WT inst)
    CARDINFO.DLL - Installation resource DLL         (read by GenIn.dll)
    CWINST.DLL   - Crystal installation executable   (called by minstall.exe)
    READ.ME      - This file


5)  Crystal Audio for OS/2 Installation Procedure
-------------------------------------------------------------------------------
To install device support, insert the Crystal Audio for OS/2 diskette in
drive A: (or whichever drive Crystal Audio for OS/2 diskette is in).
Start the Multimedia Application Install program which is located in the
Multimedia folder on the OS/2 desktop.
Alternatively, you can execute MINSTALL from an OS/2 command prompt.

Once you are in the multimedia installation program, select
Source Drive A: (or whichever drive Crystal Audio for OS/2 diskette is in).

The installation program will show
   Crystal Audio      (Pre-selected)
   IBM OPL-3 FM MIDI  (Pre-selected)

Click the install button to proceed with the installation.  Read and follow
the instructions provided by the installation program.

The following files are installed:

If system is Pre-Merlin  (Pre OS/2 Warp version 4 - Update CLOCK drivers)
   \OS2\BOOT\CLOCK01.SYS        IBM high resolution timer support
   \OS2\BOOT\CLOCK02.SYS        IBM high resolution timer support
   \OS2\BOOT\TIMER0.SYS         IBM high resolution timer support

If system is Pre-Merlin  (Pre OS/2 Warp version 4 and fixpack level < 26)
   \MMOS2\DLL\AMPMXMCD.DLL      IBM DLL for mixer API/DART (from DART DevCon)
   \MMOS2\DLL\AUDIOIF.DLL       IBM DLL for mixer API/DART (from DART DevCon)

If system is Pre-Merlin  (Pre OS/2 Warp version 4 and fixpack level is 26)
   \MMOS2\DLL\AMPMXMCD.F26      IBM standard FP 26 DLL (un-do prior installs)
   \MMOS2\DLL\AUDIOIF.F26       IBM standard FP 26 DLL (un-do prior installs)

If system is Pre-Merlin  (Pre OS/2 Warp version 4 and fixpack level > 26)
   No MMPM/2 system DLLs are updated

If IBM OPL3 is installed:
   \MMOS2\OPL3.SYS             IBM FM Driver
   \MMOS2\DLL\OPL3RES.DLL      IBM FM Driver runtime support DLL
   \MMOS2\INSTALL\MIDIPLAY.ICO Installation ICON

If Crystal Audio is installed:
   \OS2\BOOT\CWAUDIO.SYS        Crystal OS/2 Audio device driver
   \MMOS2\CWVAUDIO.sys          Crystal OS/2 Virtual Device Driver
   \MMOS2\DLL\CWINST.DLL        Crystal installation DLL

These lines lines will be added to the OS/2 CONFIG.SYS file.:
    BASEDEV=CWAUDIO.SYS /N:BSAUD1$ /X1:50 /X2:50 /LCAPT:X1X2
    DEVICE=C:\MMOS2\CWVAUDIO.SYS BSAUD1$

If OPL-3/FM is installed:
    BASEDEV=TIMER0.SYS
    DEVICE=C:\MMOS2\OPL3.SYS /P:388 /N:OPL31$


6)  Device Driver Command Line Options
-------------------------------------------------------------------------------
The following tables describe the various command line options and setting
available for the Crystal Audio device drivers.

The options for setting IRQ/IO/DMA should be used only where
the default settings, BIOS assigned settings or operating system
assigned settings are not appropriate.

Run driver with "/V" to query how the codec was initialized.
See section "10" for more information.

CWAUDIO.SYS    -   OS/2 audio configuration device driver.

Option/Format  Description           Valid Values (* = Default Value)
--------------------------------------------------------------------------------
/N:<name>      Name of PDD           BSAUD1$ (Supplied by install)
/V             Verbose Display
/X1:<percent>  AUX1 unmute/gain      0..100 (decimal) (*50) (usually "Line-In")
/X2:<percent>  AUX2 unmute/gain      0..100 (decimal) (*50) (usually CD-ROM)
/L:<percent>   LINE unmute/gain      0..100 (decimal) (*100)(FM volume)
/LCAPT:<input> Line-In record source X1, X2, *X1X2, L (X1X2 is mixed aux1+aux2)
/T:<value>     Inactivity power down 1..5 minutes     (*1)
/MBY:<0,1>     Mono bypass           *1 (mono-in connected to mono-out)
/MIM:<0,1>     Mono input mute       *1 (mono-in not connected to input mixer)
/MOM:<0,1>     Mono out mute         *0 (audible)
/XCTRL0:<0,1>  XCTRL0 Pin set        System specific.  Sometimes used to
/XCTRL1:<0,1>  XCTRL1 Pin set        control power to amplifier.  On IBM
                                     Aptiva with Bose speakers, set both to 1

/P:<port>      Codec Port            *534, 608, (530..FF8, divisible by 4)
/I:<irq>       Codec IRQ             *5, 7, 9, 11, 15 (decimal)
/D:<pDMA,cDMA> Codec DMA             0, 1, 3 (Default 1,0)
/C:<port>      Control Port          120, *538, (120..FF8, divisible by 8)
/J:<port>      Joystick Port         *200, 208, NONE
/S:<port>      Sound Blaster Port    *220, 240, 260, 280, NONE
/M:<port,irq>  MPU Port and IRQ      *330, NONE, (300..3E0, divisible by 8)
                                     IRQ: 7, 9, 11, 12, 15, *NONE
/F:<port>      FM synth port         *388, NONE, (388..3F8, divisible by 8)



CWVAUDIO.SYS   - OS/2 audio virtual device driver.

Option/Format  Description               Valid Values (* = Default Value)
---------------------------------------------------------------------------
               Name of PDD              Supplied by install program (*BSAUD1$)
/S             Skip DOS Envir Var Scan  (*not enabled)


OPL3.SYS       - IBM FM/OPL-3 MIDI Synthesis Physical Device Driver

/P:nnn         Base I/O: Sets the base I/O address for FM device.
               Is almost always, 388 (nnn is in hex)



7) Notes on Command Line Options
-------------------------------------------------------------------------------

 CWVAUDIO.SYS /S Option:
 The CWVAUDIO.SYS driver will automatically set a 'BLASTER' DOS environment
 variable to the proper audio hardware settings.  This is done by adding a
 '@SET BLASTER=' line to the beginning of all DOS session's autoexec file.
 This file is specified in DOS session's DOS_AUTOEXEC property.  The /S option
 for CWVAUDIO.SYS will skip the automatic setting of this environment variable.


8) Using Audio in DOS and Win-OS/2 Sessions
-------------------------------------------------------------------------------
Crystal Semiconductor device drivers provide outstanding support for WinOS2.

- Crystal Windows drivers are automatically installed for WinOS2 use.
- Crystal Windows drivers are OS/2 aware and communicate with OS/2 audio
  drivers to manage concurancy issues.


For most users, this support prevents concurancy related errors from
occuring.  Still, they can occur.  Some details on concurancy and
other tips for WinOS2 and DOS game execution follow:


The installation automatically configures WinOS2 Audio when you install Crystal
Audio drivers.  Windows audio drivers are installed for OS/2 Fullpack systems
only.  OS/2 Red Box systems which use the Microsoft Win 3.1 binaries will use
the Crystal Audio Windows 3.1 drivers that are used in native DOS/Win 3.1.
In either installation case, the Crystal Audio drivers used for WinOS2 are
the same.  That is, there is no special set of drivers for WinOS2.

The Crystal Windows 3.1 drivers are OS/2 aware and when loaded under WinOS2
communicate with the OS/2 Physical Device Drivers to negotiate access to
the audio device.

To enable game processing, the following DOS properties are commonly set.
This is not done automatically by the installation.  Many of the below
DOS properties default to the correct settings.

    WIN_RUN_MODE                 3.1 ENHANCED COMPATIBILITY
    AUDIO_ADAPTER_SHARING        Required
    INT_DURING_IO                On  ( This is the most critical setting )
    HW_TIMER                     On
    VIDEO_SWITCH_NOTIFICATION    On
    VIDEO_8514A_XGA_IOTRAP       Off
    VIDEO_RETRACE_EMULATION      Off ( This setting critical for graphics )
    DPMI_MEMORY_LIMIT            8


9) Audio Concurrency Issues - OS/2, DOS, Win-OS/2
-------------------------------------------------------------------------------

When you have a single audio device, it is not possible for two programs
to use the device at the same time.  For example, if one application has
the device configured for audio playback, and a second application
also wishes to perform audio playback, a conflict exists.

The OS/2 multimedia subsystem (MMPM/2) is designed such that, when an
application is running in the foreground (has focus), then that application
takes priority over others running in the background.
MMPM/2 manages the device contention, forcing pauses and resumes to
pass use of the device to the current focus application.

This robust support is only available for OS/2 native applications.

When DOS games or WinOS2 drivers try to use the device, MMPM/2 is not
involved and cannot force an application off the device.  When the DOS
environment is using the audio device, MMPM/2 is locked out.
This creates an opportunity for contention.

To minimize the impact of this problem, Crystal Semiconductor's WinOS2
drivers are OS/2 aware.  They communicate with their OS/2 counterparts
to release use of the device at all times when WinOS2 is quiet.
This is a vast improvement versus many other OS/2 device driver sets.

When WinOS2 is quiet, it is "idle" and will not prevent MMPM/2 or other
WinOS2 or DOS sessions from using the device.  This also allows you to
run multiple separate WinOS2 sessions with no concern of audio sharing
between the sessions.

MMPM/2 by contrast considers the device "busy" when ever an OS/2
multimedia application is loaded.  For example, loading the OS/2 shipped
Digital Audio player will prevent WinOS2 from using the audio device.
This is often not an issue as the most prevalent OS/2 multimedia
application, system sounds, releases the device after each sound is played.

DOS games are unaware of other entities in the system and
do not respond well to being kicked off the device.
A running DOS game will prevent OS/2 and WinOS2 from using the audio device.


For more information on this subject, see OS/2 online documentation

    VIEW /AUDIO
    VIEW /MULTIMEDIA
    VIEW /SOUNDS


10) Plug and Play System Issues
-------------------------------------------------------------------------------
PnP configuration is used to assign IRQ/IO/DMA resources to the Crystal
audio device.

The following entities can perform PnP configuration:

1. OS/2 Warp 4.0 configuration manager.  Warp 3 is not PnP aware.
2. PnP ISA BIOS - common on desktop computers
3. PnP BIOS System device node - common on notebook computers
4. Crystal audio driver can perform its own PnP initialization.

The final device settings are based on a set of default values
in the device driver.  The driver communicates with the operating
system and BIOS at boot to receive information on how these
entities may have configured the audio device.
Finally, the driver supports command line overrides so that
the user can specify a particular set of resources.

Where the final settings are different from the BIOS/OS settings,
the device driver performs its own PnP sequence to configure the
audio codec.

The use of overrides should not be necessary as the assignment of
resources to devices is a responsibility of the operating system and
system BIOS.  While OS/2 Merlin is a PnP aware OS, it provides no
means for a user to override an OS assigned resource.   This makes
support of device driver overrides a necessiry.

Additionally, the Warp 4 OS does not (by default) perform a full
PnP isolation on each boot.  It is possible for discrepancies
to arrise where the OS database of installed devices does not
match the hardware that is actually installed.  This will result
in incorrect information being provided to the device driver at
initialization.  You can command an OS/2 full PnP sequence by
pressing Alt-F1 early in the boot sequence and selection option, F5.

The audio driver follows the sequence below for PnP initialization.

1.  Crystal audio device driver has default values
2.  PnP ISA BIOS is queried to see if it has configured the audio device.
3.  Warp 4 PnP manager may specify values that it has assigned.
4.  PnP BIOS is queried regarding system device nodes (notebook computers)
5.  User supplied command line parameter override Warp and BIOS PnP settings


11) Mixer Issues
-------------------------------------------------------------------------------
As of this release, there is no generic OS/2 mixer application.
Therefore, the volume control for devices attached to mixer LINE, AUX1,
and AUX2 is established on the command line of the CWAUDIO.SYS driver.
Refer to section 6, CWAUDIO.SYS, for the format of the unmute and gain
setting  options.

These values for gain are set on each boot and cannot be altered during system
operation.  The command line values represent a percentage range 0..100 where
0 is mute and 100 is maximum volume.
NOTE: This is different than the format of these parameters in earlier
version of the Crystal audio drivers where the settings were dB attenuators.

The devices attached to LINE, AUX1, and AUX2 are system dependent but
generally reflect CD-ROM audio playback and sound card line-in jack.
Refer to your system documentation for device configuration.
With the default installation, all inputs are un-muted - which makes CD-ROM
audible.

Note:  These settings do not effect standard wave audio volume or record
source and gain which are controlled by the OS/2 volume control icon and
application sliders.


12) MIDI Synthesis
-------------------------------------------------------------------------------
This installation diskette includes support to install the IBM OPL3
device driver.   All of the Crystal Semiconductor audio codecs which
support this device driver include an integrated FM synthesizer.

The installation pre-selects the IBM OPL3 driver and will install
it unless you de-select this item.

You may find that the default FM playback volume is too high or too low.
The output of the FM part is routed through the Crystal Audio CODEC and
its gain/attenuation can be adjusted by changing mixer command line
options on the CWAUDIO.sys audio device driver.


13) Web Site - where to get updated drivers
-------------------------------------------
This device driver supports the following Crystal Semiconductor CODECS:
   CS4236B, CS4237B, CS4238B, CS4235, CS4239
These parts are "mode 3" capable.

This device driver should not be used for:
   CS4231, CS4232, CS4236
These parts are "mode 2" capable.  Please get the version 1.xx driver
from the Crystal Semiconductor web site: http://www.crystal.com


14) Special notes on upgrading from driver version 1.xx to 2.xx.

The Crystal Audio driver included in this package has been
significantly enhanced to utilize Crystals "mode 3" codecs.

The driver provides the following enhancements:
a) Supports Crystal "mode 3" audio CODECS:
      CS4236B, CS4237B, CS4238B, CS4235 and CS4239

   CS4231, CS4232, CS4236 customers should use driver version 1.7x
   which is available on the Internet:
      http://www.cirrus.com/drivers/audiodrv/

a) Full duplex play and record of independent data formats at
   independent sample rates.  On prior driver, the data format
   could be different, but the same rate had to be the same.

b) Support for INPUT Mixer.
   Crystal mode 3 codecs can mix input sources in the same
   manner that other devices can mix output signals.
   That is, multiple input sources can be active at one time.
   The signal recorded is the summation of all the selected sources.

   OS/2 API is however input "mux" (mutially exclusive) orientated.
   It provides the ability to select record sources "Line-In" and "Mic".

   On past device drivers, the logical concept of "Line-In" has defaulted
   to codec input Aux-2.  This did not work for all people as the
   assignment of signals to codec (chip) inputs is board specific.
   To work around board specific issues, the driver provides a
   command line switch to specify the assignment of "line-in".

   The new driver is able to associate Line-In to the summation of
   Aux-1 and Aux2 which will work in most cases for CD-Audio record.
   Where necessary, the logical to physical mapping of "Line" can
   be specifically stated with the (/LCAPT:).

c) Warp 3 FixPack 26 detection during install ( Warp 3 only )
   Some Warp 3 users have noted that Warp 3 fixpack 26 has OS/2 DART
   support which is better than the DART support installed with prior
   versions of the Crystal installation.   We have historically
   installed MMPM/2 DART DLLs which came from the Developers
   Connection DART CD-ROM.  (ampmxmcd.dll and audioif.dll)
   The Developers Connection version of these DLLs is slightly older
   than the DART support included with MMPM/2 in fixpack 26.

   To accommodate both Warp 3 FP26 users and Warp 3 no-fixpack users,
   the Crystal installer has been updated to auto-detect FP26 and
   install DART DLLs appropriate to the service level of the target system.

   All files replaced during installation are backed up before being replaced.
   Check file \mmos2\install\minstall.log for details on actions taken
   during installation.

   Warp 4 (Merlin): The Crystal installer checks OS/2 version and only
   performs the system component updates on Warp 3 systems.

15) Problems/Questions
-------------------------------------------------------------------------------
Please e-mail problems/questions to the following address:
montalvo@crystal.cirrus.com
