CS423x OS/2TM
Software OEM Reference Manual








Revision 1.60
Covers Crystal Audio Drivers Version 1.60
Print Date and Time: September 9, 1996






PRELIMINARY



Software License Statement
The software described in this manual is protected by U.S. and international copyright laws. You may not copy the software for any purpose other than making archival copies for the sole purpose of backing-up the software for protection against loss. A separate Software License may be obtained from Crystal that allows reproduction and distribution of the software.
The software may not be used on two or more machines at the same time.

Limit of Liability 

In no event will Crystal be liable to you for any consequential or incidental damages, including any lost profits or lost savings, even if a Crystal representative has been advised of the possibility of such damages, or for any claim by any party. 
Some states do not allow the exclusion of limitation of incidental or consequential damages, so the above limitation or exclusion may not apply to you. 












Information in this document is subject to change without notice.
(c) 1996 Crystal Semiconductor Corp.  All rights reserved.
Reproduction in any manner whatsoever without the written permission of Crystal Semiconductor Corporation is strictly forbidden.
OS/2 and Warp are registered trade marks of IBM Corporation.
Sound Blaster and Sound Blaster Pro are registered trade marks of Creative Labs.
AdLib is a registered trade mark of AdLib Corporation
All brand and product names mentioned herein are trademarks or registered trademarks of their respective holders.  Crystal Semiconductor Corporation disclaims any proprietary interest in trademarks and trade names other than its own.

Table Of Contents
TABLE OF CONTENTS	
CHAPTER 1: INTRODUCTION	
CHAPTER 2: OVERVIEW	
OVERVIEW	
RESOURCE DATA	
CHAPTER 3: INSTALLATION	
Installing on top of previous installations	
System Requirements	
File List for Crystal Audio Install Disk	
Crystal Audio for OS/2 Installation Procedure	
Device Driver Command Line Options	
Notes on Command Line Options	
CWAUDIO.INI vs. Command line options	
CWVAUDIO.SYS /S Option	
CWAUDIO.SYS /R Option	
Using Audio in DOS and Win-OS/2 Sessions	
Audio Concurrency Issues - OS/2, DOS, Win-OS/2	
Plug and Play System Issues	
Mixer Issues	
MIDI Issues	
Web Site - where to get updated drivers	
Crystal Web Page:	
Problems/Questions	


Chapter 1: Introduction
This manual describes the software package supplied with the CS423x audio codec and covers how to install and use these programs. The package includes a OS/2  driver and support programs. This manual was designed for technicians, programmers, and engineers who need reference information about the Crystal Semiconductor CS423x OS/2 Software Kit.
This document provides generic information concerning the CS423x OS/2 Software Kit. For specific information refer to the release notes for the relevant release.
This Software Kit can be used  directly on the CRD4236-1 Audio Card and other Crystal Semiconductor reference designs and evaluation boards, including, CRD4232-1, CRD4232-2, CRD4232-3, CRD4236-3 and CRD9233-1. This Software Kit will also work with CS4237B and CS4238B audio codecs but will not take advantage of the sound enhancement features of these parts.  For full details on the Crystal reference designs and evaluation boards, please refer to the relevant Crystal Data Sheet.


            Chapter 2: Overview
This chapter describes the contents of the CS4232/6 OS/2 Software Kit and how to install the audio driver and support programs.
Overview
The software contained in the CS4232/6 OS/2 Software Kit consists of setup/installation files, OS/2  drivers and DOS support programs.
Resource Data
To operate correctly in a Plug & Play environment, the CS423x must be loaded with appropriate resource data. This can be achieved in several ways, the most secure of which  is from an external EEPROM. Resource data and utilities are included on a separate disk.
Please refer to the Crystal codec data sheet and the RESOURCE.TXT file on the CS423x Utility disk.
Many of the examples and screen shots in this document will vary according to specific resource data entries.
Resource data can be used to configure the Crystal codec for Plug & Play operation or to disable BIOS Plug & Play operation. On the CS423x Utilities Disk, two batch  files, PNP36.BAT and NOPNP36.BAT can be found. Running these batch files will program the EEPROM with data which enables or disables BIOS Plug & Play operation respectively. Boards are generally shipped from Crystal Semiconductor with Plug & Play disabled, though this is subject to change.
Note:  If the EEPROM of a CS4232 is programmed, the system MUST be rebooted so that it goes through a power cycle.
                                               Chapter 3: Installation
 Installing on top of previous installations 
This installation program supports installation over previous installations of Crystal Audio device drivers as well as over-installation of IBM's OPL-3 and MPU-401 device drivers. 
No de-install is necessary prior to executing the OS/2 Multimedia installation program.
System Requirements 
This installation and device drivers work on the following OS/2 systems:
    OS/2 Warp Version 4  ( Merlin )
    OS/2 Warp Connect    ( Warp - Blue box )
    OS/2 Warp Fullpack   ( Warp - Blue box )
    OS/2 Warp Version 3  ( Warp - Red box )

In the above "Blue box" and "Red box" 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.
File List for Crystal Audio Install Disk 
Crystal Audio Files 
BSAUDRES.DLL    
   OS/2 business audio support DLL. 
CARDINFO.DLL    
   Crystal device support DLL. 
CWAUDIO.HLP     
   Help file used during installation. 
CWAUDIO.BIN     
   Audio device microcode. 
CWAUDIO.INI     
   file for overriding audio device settings. 
CWAUDIO.SYS     
   Audio physical device driver. 
CWINST.DLL
   Installation support DLL
CWCONFIG.SYS    
   Audio device configuration device driver.
CWVAUDIO.SYS    
   Audio virtual device driver. 
CONTROL.SCR     
   Installation control file. 
FILES.SCR       
   Installation file list. 
RESOURCE.SYS
   IBM PnP Resource Manager (Warp Only)
RMVIEW.EXE
   IBM PnP Resource Manager (Warp Only)
RMINFO.DLL
   IBM PnP Resource Manager (Warp Only)
TIMER0.SYS
   IBM Highres timer driver (Warp Only)
CLOCK01.SYS
   IBM ISA clock driver (Warp Only)
CLOCK02.SYS
   IBM MCA clack driver (Warp Only)
AUDIOIF.DLL     
   Updated DLL for mixer support.
AMPMXMCD.DLL    
   Updated DLL for mixer support.

IBM OPL3 Files 
OPL3.SYS        
   OS/2 audio physical device driver for IBM OPL3 FM MIDI. 
OPL3RES.DLL     
   IBM OPL3 device support DLL. 
OPLREAD.ME      
   Documentation for IBM OPL3 FM MIDI installation. 
		 
IBM MPU401 Files 
MPU401.SYS      
   OS/2 audio physical device driver for IBM MPU401 MIDI. 
MPURES.DLL      
   IBM MPU401 device support DLL. 
MPUREAD.ME      
   Documentation for IBM MPU401 MIDI installation. 
  
IBM Misc. Files 
MIDIPLAY.ICO	
   Desktop ICON for MIDI player. 

WIN-OS/2 Drivers (Installed on Warp/Merlin full pack systems only)
CS32BA11.DRV
 Windows Wave, Aux, and Mixer Driver
CS32BA11.INI
 Wave Driver Settings
CSFM.DRV
 FM MIDI Synthesis Driver
MIDIMAP.CFG
 Midimapper for FM MIDI Driver
CWADD.INI
 Sndsys Settings For System.ini

  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)
   IBM MPU-401        (Not Pre-Selected)

Most users will want to just "hit enter" to kick off the install.  If your system has wavetable synthesis hardware, or if you have an external MIDI instrument attached to your computer, you will also wish to select the MPU-401 device driver.
Click the install button to proceed with the installation.  Read and follow the instructions provided by the installation program.  The following files will be moved onto your system, based on the devices selected :
If Crystal Audio is installed :
   \MMOS2\DLL\BSAUDRES.DLL
   \MMOS2\CWAUDIO.SYS
   \MMOS2\CWAUDIO.INI
   \MMOS2\CWAUDIO.BIN
   \MMOS2\CWVAUDIO.SYS
   \OS2\BOOT\CWCONFIG.SYS

If IBM OPL3 is installed :
   \MMOS2\OPL3.SYS
   \MMOS2\DLL\OPL3RES.DLL

If IBM MPU401 is installed :
   \MMOS2\MPU401.SYS
   \MMOS2\DLL\MPURES.DLL

If either OPL3 or MPU401 are installed :
   \MMOS2\INSTALL\MIDIPLAY.ICO

If system is Pre-Merlin  (Pre OS/2 Warp version 4)
   \OS2\BOOT\RESOURCE.SYS       IBM PnP resource manager
   \OS2\RMVIEW.EXE              IBM PnP resource manager application
   \OS2\DLL\RMINFO.DLL          IBM PnP resource manager application
   \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
   \MMOS2\DLL\AMPMXMCD.DLL      IBM DLL for mixer API
   \MMOS2\DLL\AUDIOIF.DLL       IBM DLL for mixer API

These lines will be added to the OS/2 CONFIG.SYS file.:
    BASEDEV=CWCONFIG.SYS /P:534 /I:5 /D:1,1 /SB:220 /M:330 /FM:388 /J:NONE /CD:NONE
    DEVICE=C:\MMOS2\CWAUDIO.SYS /N:BSAUD1$ /X1:8 /X2:8 /L:8 /LCAPT:X1
    DEVICE=C:\MMOS2\CWVAUDIO.SYS BSAUD1$


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

If MPU-401 is installed:
    BASEDEV=TIMER0.SYS
    DEVICE=C:\MMOS2\MPU401.SYS /N:MPU4011$

Device Driver Command Line Options 
The following tables describe the various command line options and setting available for the Crystal Audio device drivers.  On PnP systems, many of these command line parameters are ignored.
CWCONFIG.SYS    -   OS/2 audio configuration device driver.
Option/Format
Description
Valid Values (* = Default Value) 
/A:<asic type>
ASIC Type (CS4231 only)
OPTi928, OPTi929, MAD16, GALLANT, *NONE 
/P:<port>
Codec Port
*534, 608, E84, F44 (hex) 
/I:<irq>
Codec IRQ
*5, 7, 9, 11, 15 (decimal) 
/D:<pDMA,cDMA>
Playback, Capture DMA
0, 1, 3 (*1,1) 
/CS:<port>
Control Port
(*not required) 
/SB:<port>
Sound Blaster Port
*220, 240, NONE 
/M:<port,irq>
MPU Port MPU IRQ
330, *NONE 7, 9, 11, 12, 15, *NONE
/FM:<port>
FM Port
*388, NONE 
/J:<port>
Joystick Port
100, 200, *NONE 
/CD:<type,port>
CD-ROM Type CD-ROM Port (CS4231 only)
Sony, Mitsumi, Panasonic, *NONE 320, 330, 340, 360, *NONE
/DL:<option>
Download microcode
Force, No (*not required) 
/IFM:<option>
Internal FM (CS4236 only)
*On, Off 
/O
Override PnP settings
(*not enabled) 
/V
Enable Verbose Display
(*not enabled) 
    
CWAUDIO.SYS     -   OS/2 audio physical device driver.  This driver supports all Crystal Audio devices. 
  Option/Format
Description
Valid Values (* = Default Value) 
/N:<name>
Name of PDD
Supplied by install program (*BSAUD1$) 
/X1:<value>
AUX1 unmute/gain
0..31 (8 = 0dB)  (*not enabled - muted) 
/X2:<value>
AUX2 unmute/gain
0..31 (8 = 0dB)  (*not enabled - muted) 
/L:<value>
LINE unmute/gain
0..31 (8 = 0dB)  (*not enabled - muted) 
/R:<rate>
Enable Adj Intrpt Rate
1..60 (interrupts/sec) (*not enabled) 
/EXT
Preserve Mixer Input
(*not enabled) 
/LCAPT:<source>
Line capture source
L (line), X1 (AUX1), MX (MixOut)
/M:<option>
Microphone Monitoring
1, On (*not enabled) 
/S:<value>
Inactivity power down
1..5 minutes (*not enabled) 
/V
Enable Verbose Display
(*not enabled) 
    
CWVAUDIO.SYS     -  OS/2 audio virtual device driver.  This driver supports all Crystal Audio devices. 
 Option/Format
Description
Valid Values (* = Default Value) 

Name of PDD
Supplied by install program (*BSAUD1$) 
/S
Skip DOS Envir Var Scan
(*not enabled) 

MPU401.SYS       -  IBM MPU-401 Physical Device Driver

        Where 'x' is a single capital letter, 'n' is from 1 to 9, and 'yyy' is the option.

        /Pn:yyy  Base I/O: Sets the base I/O address for port n, usually 300 or 330 (# is in hex)

        /In:yyy  IRQ level: Sets the IRQ level for port n.  yyy is a decimal number from 1 to 15.  If the base I/O address for a given port is specified (e.g. /P1:300), but the IRQ is NOT specified, the driver will attempt to autodetect the IRQ.                 Note: Interrupts are not used for MMPM/2 MIDI playback.

        /N:sss   Driver name, an 8-character length string, ending in a $. Do not specify a port number.  Default is "MPU401$".

        /R:yyy   Resolution of MMPM/2 timing.  If the highres timer (TIMER0.SYS) is installed, this parameter tells the MPU-401 driver what resolution to use (where yyy is the number of milliseconds) when playing MMPM/2 MIDI streams.  Default is one millisecond.

        /V       Verbose output during boot.  If used, this should be the first parameter.


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)

Notes on Command Line Options 
CWAUDIO.INI vs. Command line options
There are two ways to supply CWAUDIO.SYS with options that override default  settings. The first method is by supplying command-line options in the  CONFIG.SYS file as specified above. The second method is by supplying entries  in the CWAUDIO.INI file in the \MMOS2 directory. The first method overrides  the second on an individual entry basis. Therefore, entries in CWAUDIO.INI  will be used only when that particular option is not specified in CONFIG.SYS.
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.
CWAUDIO.SYS /R Option
The CWAUDIO.SYS /R option will allow the user to adjust the device interrupt rate.  This option should be used with caution.  In most cases, an interrupt rare of 32 interrupts per second is optimal.

Using Audio in DOS and Win-OS/2 Sessions 
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 Audio.

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 or Optional 
INT_DURING_IO
On 
HW_TIMER
On 
VIDEO_SWITCH_NOTIFICATION
On 
VIDEO_8514A_XGA_IOTRAP
Off 
VIDEO_RETRACE_EMULATION
Off 
DPMI_MEMORY_LIMIT
8 
Audio Concurrency Issues - OS/2, DOS, Win-OS/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 others running in the background.  Background applications
are put on hold until they are placed in the foreground (have focus).

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
configures the device for audio playback, the application with the focus takes priority and the application in the background is placed on hold.  This situation also exists for sampling rate and sample size configuration.

Audio device drivers for Windows, installed under Win-OS/2, attempt to use the audio device in all Windows sessions.  For Win-OS/2 sessions which do not use the audio device, you can set the AUDIO_ADAPTER_SHARING property
to "None".  This prevents the session from accessing the audio device, and enables the device to be used by other applications.

Crystal Semiconductor Windows device drivers are WinOS2 aware and release the device for OS/2 use whenever they are not making sound.

To display OS/2 online documentation pertinent to system audio, use view.exe.  Suggested viewing items are:

    VIEW /AUDIO 
    VIEW /MULTIMEDIA 
    VIEW /SOUNDS 
Plug and Play System Issues 
The CS4232 and CS4236 are Plug and Play (PnP) compatible devices.  Merlin is a Plug and Play aware OS.  Warp is not.  However, after running this installation program, your Warp system will be upgraded to make it PnP aware.  ( The Merlin level resource manager is installed ).  The installation checks OS version and will not update these files 
on Merlin and post-Merlin versions of OS/2.  It also checks file date/time and will not overwrite a newer file.

Where the Crystal Device driver set can find the function of a PnP BIOS or PnP Operating System, it will use the PnP information in preference to the command line options or .INI file settings.

This means that after running this installation, many of the command line options for CWCONFIG.SYS become "no-effect" parameters.

The Crystal Semiconductor CS4231 Audio CODEC is not a PnP device.  With these systems, the config.sys command line and configuration .INI  file are not overridden by the PnP settings.  For most users, the default
settings work without conflict.
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 5, 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 gain setting where 8 is equal to 0 dB gain.  Each increment is 1.5 dB.  Values greater than 8 will reduce 
the volume and values less than 8 increase the volume.

The devices attached to LINE, AUX1, and AUX2 are system dependent and cannot be detailed here.  Refer to your system documentation for device configuration.

Note:  These settings do not effect standard wave audio volume which is controlled by the OS/2 volume control icon.
MIDI Issues 
This installation diskette allows for the optional installation of the IBM OPL3 and MPU401 MIDI drivers.  These drivers are provided to the user as a convenience.  Your system may or may not support MIDI audio.  Please refer to
your system documentation for information related to your system's ability to support MIDI.

The CS4236 Crystal Semiconductor Audio device supports an integrated FM synthesizer.  Also, most retail boards utilizing the CS4232 and CS4231 Codecs include a OPL-3 compatible hardware for game support.  In all of these
cases, the included OPL-3 device drivers will operate to provide MIDI playback on your system.

Therefore, it is recommended that you install the IBM OPL3 driver to make use of this feature.  Crystal Audio and the IBM OPL3 FM Synthesis drivers are pre-selected when you start the installation.

If your system has Wavetable Synthesis hardware such as the Crystal Semiconductor CRD9233 Wavetable daughter card, you will also want to install the IBM MPU-401 device driver.  This driver is not auto-selected on the
installation control panel.

Web Site - where to get updated drivers
Crystal Web Page:
http://www.crystal.com/support/crysoft.htm


Problems/Questions
Please contact your local Crystal Semiconductor Field Application Engineer to report problems or questions you might have.

Crystal Semiconductor Corporation                                                                      	                              Preliminary Revision 1.00
A Cirrus Logic Company

Crystal Semiconductor Corporation                                                                      	                              Preliminary Revision 1.00
A Cirrus Logic Company

ii
CS423x OS/2 Warp Software OEM Reference Manual



iii

CS423x OS/2 Warp Software OEM Reference Manual


Crystal Semiconductor Corporation                                                                      	                              Preliminary Revision 1.00
A Cirrus Logic Company

8
CS423x OS/2 Warp Software OEM Reference Manual



9

CS423x OS/2 Warp Software OEM Reference Manual


CS423x Software OEM Reference Manual 

	Table Of Contents

6-xxvi  CS4232 Software Reference Manual

CS4232 Software Reference Manual 6-xxvi  







