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

README.TXT - Crystal Semiconductor, OS/2 PCI bus Audio driver
--------------------------------------------------------------------------

This file contains information on how to install the Crystal Semiconductor
Corporation OS/2 audio device drivers for the SoundFusion(tm) PCI bus family 
of products (CS4610, CS4612, CS4614, CS4280).

The following topics are covered in this READ.ME file:      

1) Restrictions In This Release
2) Installing On Top Of Previous Installations
3) OS/2 Version 4 and Multiple MIDI and Audio devices
4) De-Installation of Entire MMPM/2 Multimedia Subsystem, and Re-install
5) System Requirements - PCI Driver Requires Full Pack Version of OS/2.
6) File List for Crystal Audio Install Disk
7) Installation Procedure
8) Device Driver Command Line Options
9) Device Driver .INI file
10) Audio in WIN-OS/2 Sessions
11) Audio in DOS Sessions
12) Audio Concurrency Issues - OS/2, DOS, Win-OS/2
13) PCI Configuration - IRQ Assignment
14) Web Site - Where To Get Updated Drivers
15) Problems/Questions


1) Restrictions In This Release - Known problems
-------------------------------------------------------------------------------
a) This release does not include WinOS2 audio support.  
   The drivers are still in development.
   Where the readme references WinOS2 audio, please ignore until 
   WinOS2 audio support is added to the device driver package.

b) No OS/2 MIDI playback support is included in the installation.
   OPL-2 support is available for DOS session games.
   OS/2 native MIDI playback support will be added at a later date.


2) Installing On Top Of Previous Installations
-------------------------------------------------------------------------------
No de-install is necessary prior to executing the OS/2 Multimedia
installation program, minstall.exe.


3) OS/2 Version 4 and Multiple MIDI and Audio devices
-------------------------------------------------------------------------------
On OS/2 Warp Version 4 (Merlin), the operating system has a bug where 
it always uses the MMPM/2 defined WaveAudio01 device for audio and 
the Sequencer01 device for MIDI.  

If the machine has more than one WaveAudio device or more than 
one Sequencer device, the WaveAudio02 and Sequencer02 devices 
are NEVER used even if the user launches a "Digital Audio 2" application.

This problem applies to system sounds and all of the GUI based 
applications that ship with the operating system.  

For more information, consult IBM OS/2 APAR:
   "JR10933 OS/2 Merlin MIDI player always uses MIDI1 device"

The system bug is a configuration issue where the workplace shell 
associates ".WAV" and ".MID" file extensions expressly with the "01" 
version of the WaveAudio and Sequencer devices.

There is no method to change the association and there is no facility
provided in the OS/2 shipped applets to select a different device.

NOTE: MMPM/2 is very capable of handling a multitude of devices.
This bug however limits the functionality.

The problem does not exist on OS/2 Warp version 3.

To work around this problem, the Crystal installation de-installs
all waveaudio and sequencer devices before installing the drivers
in this package.


4) De-Installation of Entire MMPM/2 Multimedia Subsystem, and Re-install
-------------------------------------------------------------------------------
It is not normally necessary, but should it become necessary to start
from the beginning, the OS/2 Multimedia subsystem (MMPM/2) can be 
deleted and reinstalled without impacting the rest of the installed system.

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 may auto-detect an audio device.  You should override the 
   auto-detection to remove the detected device.
   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.


5) System Requirements - PCI Driver Requires Full Pack Version of OS/2.
-------------------------------------------------------------------------------
This installation and device drivers on this diskette will work properly
only on full-pack versions of OS/2.

    OS/2 Warp 3.0            ( Warp - Red box - Not supported, see below )
    OS/2 Warp 3.0 Fullpack   ( Warp - Blue box - Supported )
    OS/2 Warp Connect        ( Warp - Blue box - Supported )
    OS/2 Warp 4.0            ( Merlin - Supported )

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.

WinOS2 audio support for the PCI driver requires installation of a 
Windows audio driver into system.ini that is specifc to OS/2.
It will NOT operate on native Windows.  

The installation into system.ini is done automatically during
"minstall" installation process.

Since this driver will not operate on native Windows, it is not 
installed on "Red box" systems.  There is a further difficulty 
on red box systems that the Windows 3.1 native PCI driver will
be present in the system.ini that OS2 uses to load WinOS2 and
the Windows 3.1 PCI audio driver will not operate in WinOS2.
This creates an error condition.

For this reason, OS/2 Warp 3 Red-Box (Half-pack) is officially 
not supported for this device driver set.

If you are aware of the limitations, half-pack systems can be used.  
On half-pack systems, the Crystal installation will not install audio 
drivers for WinOS2 execution.  It will also not modify the system.ini
of native Windows 3.1 in any circumstance.

If you have native Windows 3.1 Crystal PCI audio drivers installed, 
they must be removed for error free WinOS2 execution on Warp 3 red-box.
This requires removing the Crystal Semiconductor audio driver from 
system.ini before WinOS2 launch and returning them to system.ini for 
native Windows 3.1 execution.  This process is not automated.


6) 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
   CARDINFO.DLL - Installation control file, resource DLL.
   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
   CWADD.INI    - Installation, contains updates for system.ini
   CWC4610.OSP  - DSP tasks for CS4610 device
   CWC4612.OSP  - DSP tasks for CS4612 device
   CWCFILES.SCR - Installation control file, list of files to copy
   CWCFM.OSP    - DSP tasks for FM music synth
   CWINST.DLL   - Crystal installation executable, called by minstall.exe
   CWCIOTRP.OSP - DSP tasks for FM music synth, intercept 0x388 port range
   CWCMMPM.INI  - Audio driver settings.  Text file.  User changable.
   CWCMMPM.SYS  - Audio device driver
   CWCSPUD.INI  - DSP manager configuration settings.  User should not change.
   CWCSPUD.SYS  - DSP manager device driver
   CWCUTIL.EXE  - DSP manager utility application
   CWGMSG.SYS   - DSP manager messaging device driver
   CWGUTIL.SYS  - DSP manager utility device driver
   CWINST.DLL   - Installation DLL.  Called by minstall.exe at install time.
   INSTALL.CMD  - Installation.  Support double-click start of minstall.exe
   README.TXT   - This file
   TIMER0.SYS   - IBM High res timer driver/clock, installed on Warp only


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

   Warp 3 - Multimedia installation program is located inside 
            the Multimedia folder, on the OS/2 desktop.

   Warp 4 - Multimedia installation program is located inside the 
            System Setup folder.  The System Setup folder is located
            inside the OS/2 System folder, on the OS/2 desktop.

Alternatively, you can execute MINSTALL from an OS/2 command prompt 
or browse the installation diskette with the OS/2 "drives" utility and
double-click on the ICON for "install.cmd".

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 PCI  (Pre-selected)

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

NOTE: To remove audio and MIDI drivers, select zero devices when 
prompted for the number of devices to install.  
Selectable choices are 0 and 1.

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 Crystal PCI Audio is installed:
   \OS2\BOOT\CWCMMPM.SYS        Crystal OS/2 Audio device driver
   \OS2\BOOT\CWCSPUD.SYS        Crystal DSP manager device driver
   \OS2\BOOT\CWGMSG.SYS         Crystal DSP manager messaging device driver
   \MMOS2\CWGUTIL.SYS           Crystal DSP manager utility device driver
   \MMOS2\CWCUTIL.EXE           Crystal DSP manager utility application
   \MMOS2\DLL\CWINST.DLL        Crystal installation DLL

These lines lines will be added to the OS/2 CONFIG.SYS file.:
   BASEDEV=CWGMSG.SYS
   BASEDEV=CWCSPUD.SYS
   BASEDEV=CWCMMPM.SYS /N:CWCAUD1$
   DEVICE=C:\MMOS2\CWGUTIL.SYS
   RUN=C:\MMOS2\CWCUTIL.EXE


8) Device Driver Command Line Options
-------------------------------------------------------------------------------
The following tables describe the audio driver command line options.

CWCMMPM.SYS    - Audio device driver command line options

Option/Format  Description           Valid Values (* = Default Value)
---------------------------------------------------------------------
/N:<name>      Name of PDD           CWCAUD1$ (Name assigned by minstall)

There are no other parameters.  

Device driver options should be set via configuration file, CWCMMPM.INI.


9) Device Driver .INI file
-------------------------------------------------------------------------------
An extensive set of configurable options are contained in the 
file \mmos2\cwcmmpm.ini.  There are no config.sys command line equivalents.

All of the configurable settings are listed in the file along with 
comments describing their defaults and selectable values.

All changes take effect the next time the system is booted.


10) Audio in WIN-OS/2 Sessions
-------------------------------------------------------------------------------

<TBD> NOTE: This section does not yet apply as the WinOS2 PCI driver
<TBD> is still in development.

Crystal Semiconductor device drivers provide outstanding support for WinOS2.

- Crystal WinOS2 audio drivers are automatically installed during
  installation of OS/2 native audio device drivers.

- Crystal WinOS2 drivers are OS/2 specific and communicate with the 
  native OS/2 audio driver to perform audio operations.

- The audio device is considered "in-use" only when WinOS2 is 
  actively making sound.

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.

The Crystal WinOS2 drivers are OS/2 specifc and when loaded under WinOS2
communicate with the OS/2 native audio device drivers to perform audio.


11) Audio in DOS Sessions
-------------------------------------------------------------------------------

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.  INT_DURING_IO does not
default properly and it is the most critical setting for DOS game execution.

    WIN_RUN_MODE                 3.1 ENHANCED COMPATIBILITY
    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

Most DOS games are written to directly program a Sound Blaster Pro or
compatible device for wave audio and/or an Adlib or Sound Blaster 
compatible FM device such as the Yamaha OPL-2 or OPL-3.

With Crystal PCI Audio, no Sound Blaster compatible audio is provided
for DOS session execution.  OPL-2 FM is available.  It will usually 
be referred to as 'music' or 'Adlib' inside game configuration panels.


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

MMPM/2
------
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 applications which do not have focus.
MMPM/2 manages the device contention, forcing pauses and resumes to
pass use of the device to the foreground application.

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

DOS GAMES
---------
With the PCI parts, there is no Crystal provided support for 
Sound Blaster style audio in an OS/2 DOS session. 
FM (OPL-2) is supported.

FM does not suffer the same restrictions that traditionally cause 
sharing issues between OS/2 native and DOS game execution.  
If OS/2 MIDI playback is occuring concurrently with a DOS game 
programming the FM device, the two device drivers will cause each
other to play improper sounds, but no catestrophic errors will occur.  
That is, the system will not trap or hang.

The value of no contingincy issues is greater than the downside of
some bad sounds produced by the FM chip.

For this reason, access to the FM device is never denied.
Erroneous notes produced by the FM device usually cure themselves
as the part is continusouly progammed to make game style music.

WinOS2
------
When WinOS2 is quiet, it is "idle" and will not prevent MMPM/2 or other
WinOS2 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" whenever 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.

For more information on this subject, see OS/2 online documentation
    VIEW /AUDIO
    VIEW /MULTIMEDIA
    VIEW /SOUNDS


13) PCI Configuration - IRQ Assignment
-------------------------------------------------------------------------------
PCI devices do not participate in PnP ISA configuration.

The traditional issues of configuring IRQ/IO/DMA resources among
all of the system's ISA devices do not apply.  PCI devices are 
configured by the system BIOS - and ONLY by the system BIOS.

The OS/2 operating system queries the BIOS at runtime to determine
what PCI resources have been allocated to which PCI devices. 
The Crystal audio driver asks OS/2 to determine if its device is 
present and queries the resources that have been assigned.

The Crystal Semiconductor PCI audio device has 3 resources.
   1) Base address 0
   2) Base address 1
   3) IRQ
   4) Optionally, FM I/O ports, 0x388..0x389

Memory resources are assigned by the BIOS to physical memory
addresses that are above the limit of the machines physical memory.

PCI interrupts are also assigned by the BIOS.  PCI interrupts 
are, by definition, shareable.  Multiple devices can be assigned
to the same PCI interrupt.

For the most part, this means the traditional ISA style concerns 
over resource allocation are not an issue on PCI.  The only issue
that can arrise is the PCI use of an IRQ that is wanted for ISA.

Switching a PCI device to a different IRQ is the domain of the
system BIOS.  On many systems, the IRQ assigned to a PCI device
is configurable via the PC's setup panel.  On others it is fixed.
In all cases, the OS/2 operating system and the Crystal Semiconductor
PCI audio device will use the resources assigned by the BIOS.
There is no provision for runtime override.

FM I/O ports
------------
The FM OPL-2 I/O ports at locations 0x388..0x389 are conditionally
installed.  At boot time, the Crystal PCI device driver queries 
the presence of other providers of FM hardware.   

If no other device is providing support for FM hardware, the device
driver loads DSP tasks to implement FM and hooks the 0x388..0x389 I/O range.
Note: The check for presence of FM hardware is done very late in boot
sequence - allowing all other device drivers an opportunity to install
their hardware before the DSP task is potentially loaded.

This means that if your system has an ISA audio device installed
that implements FM, that device will be used for game processing
in preference to the PCI implementation.

                                                  
14) Web Site - Where To Get Updated Drivers
-------------------------------------------------------------------------------
This device driver supports the following Crystal Semiconductor devices
   CS4610, CS4612, CS4614, CS4280

This device driver should NOT be used for any of the Crystal Semiconductor
ISA audio CODECs, including the CS4231, CS4232, CS4236, CS4236B, CS4237B, 
CS4238B, CS4235 and CS4239.

Updated OS/2 drivers are posted on the Cirrus Logic corporate web site.

      http://www.cirrus.com/drivers/audiodrv/


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