RESOURCE.TXT  9/13/95

For differences between version 1.95 and 1.90 see the HISTORY section below.

This file (RESOURCE.TXT) describes the command line switches and commands for 
the RESOURCE.EXE program. The version number associated with this file is 
shown in the Help screen near the end of this file. When the program is run 
with the display switch OFF, the program uses exit codes to indicate that an 
error occurred. An exit code of 0 indicates everything worked okay. Exit codes 
are listed at the end of this file. 

RESOURCE is being designed to support three functions:
        1. Program an EEPROM connected to the CS4232 peripheral bus.
        2. Generate a file to include in a BIOS load - "hostload"
        3. Support debugging efforts

Programming an EEPROM is supported in two ways. 
First, and generally the most used:
        Read in a file with resource data
        Program the EEPROM.

A second, and less likely way, would be to
        Read in a file with resource data
        Write a binary file for programming on EEPROM programers. 

The second function is to generate a file for including in BIOS loading code. 
The steps would be:
        Create/modify a .INI file to specify resources
                (Must contain "DataType = HostLoad" parameter)
        Read .INI file
        Write .ASM or .C file based on the type of BIOS code needed
        Then include the written file in the BIOS code as a data block

The third function is as a debug tool. For this, the program can read the 
EEPROM or CS4232 IC and disassemble the data.

P---L---T1----+-T--2----T----3--T-+----4T---+---T5----+-T--6----T----7--T-+--R  

------------------------------------------------------------------------------
RESTRICTIONS:
-------------
1. When interfacing to the CS4232 IC, CS4232C.EXE MUST be run prior to running 
    RESOURCE -  OR THE SYSTEM WILL HANG. A RAM patch must be downloaded to 
    fix a problem when talking to the CS4232 IC. To avoid this problem, the 
    /m switch from the command line may be used (it will disable internal IC 
    reads along with the I command) Also Reading and writing files will work 
    without the patch code. 

2. EEPROM device select must start 1010aaar, where aaa (see 4) is the device 
    select or the block address, and r is the read/write bit. 

3. EEPROMS should support the block address bits A2-A0. These are used to 
    indicate the EEPROM length. Examples: 
        Exel      24C??   does
        Exel      XL24C0? does NOT
        Atmel     AT24C?? does
        Xicor     X24C??  does
        Xicor     X24042  does 
        MicroChip 24LC0?  does NOT

4. Minimum EEPROM size = 128 bytes, maximum size = 2048 bytes

5. EEPROMS MUST support the following page mode writes  - EEPROM Size:
        256  bytes - 1 block  - Page write size  1 byte
        512  bytes - 2 blocks - Page write size  4 bytes
        1024 bytes - 4 blocks - Page write size 16 bytes
        2048 bytes - 8 blocks - Page write size 16 bytes
------------------------------------------------------------------------------
EEPROMS TESTED: 
---------------
Atmel - AT24Cxx series
MicroChip - 24LCxxB series
SGS Thompson - ST24Cxx series
Xicor - X24Cxx series, X24042, X24164
Catalyst - CAT24C02
National - NM24C04L
------------------------------------------------------------------------------
COMMAND LINE PARAMETERS: 
-----------------------
Generally the program is run without command line switches. The command line 
switches are typically used in batch files. Switches are case insensitive and 
the order of switches on the command line is unimportant. The format is: 
a '/', 
followed by a one character command line switch, 
followed by an '=' - if the switch takes an argument,
followed by the actual argument - if the switch takes an argument 

SWITCHES:
P---L---T1l---+-T--2-l--T----3--T-+----4T---+---T5----+-T--6----T----7--T-+--R  

a - CONTROL logical device (2) address. Tells the program where the CONTROL 
    Logical Device is. The default is 0x538. The program must find the CONTROL 
    Logical Device to access the actual EEPROM or the internal CS4232 RAM. The 
    argument defaults to decimal; hex can be entered by starting the argument 
    with '0x' as shown in the example:                             
                RESOURCE /a=0x538

f - Force CONTROL logical device address. This command forces the CONTROL 
    Logical Device address, using the Crystal Key. This command guarantees 
    that the CONTROL logical device will be found. But, no other software will 
    know where the CONTROL logical device is. Therefore, the if other software 
    needs the CONTROL LD, the system will have to be rebooted. The argument 
    defaults to decimal; hex can be entered by starting the argument with '0x' 
    as shown in the example: 
                RESOURCE /f=0x120

d - Display Mode. Generally used in batch mode to inhibit the display of 
    status. The default is on. When this switch is set to 'off', exit codes 
    are used to indicate error status (exit code 0 = no error) Example:
                RESOURCE /d=off

e - Program EEPROM. Requires that the CONTROL logical device be known. 
    Programs and verifies the EEPROM from a previously read file. Example:
                RESOURCE /r=typical.ini /e

h or ? - Command Line Help. No arguments. Example: (listing shown later)
                RESOURCE /h 

r - Read File. Reads in the file specified. The format is determined by the 
    extension. See the Read command 'R' below for valid extensions. This 
    command line parameter is generally used in conjunction with writing a 
    file or programming the EEPROM from a batch file. Example:
                RESOURCE /r=typical.ini

w - Write File. Write the file specified from a previously read file. The 
    format is determined by the extension. See the Write command 'W' below for 
    valid extensions. Example: 
                RESOURCE /r=typical.ini /w=typical.asm

m - Minimial IC checking. Blocks the I command and disables all CS4232 
    internal RAM reads. Typically used by programs that do not want to load 
    the DOS driver before talking to the EEPROM. 


------------------------------------------------------------------------------
COMMAND LINE HELP SCREEN: 
------------------------
The following is seen when 'RESOURCE /h' is run:


        /<switch>=<parameter>

         <switch> <parameter>

            m     Minimal IC checks (Disables IC Read Command)
            a     CONTROL Logical Device Address <Dec|Hex>
            f     Force CONTROL Logical Device Address <Dec|Hex>
            d     Display mode <on|off>
            h     Command line help - this screen (no parms)

            r     Read file <rFileName>
                    Example: Resource /r=typical.ini

            w     Write (rFileName) to <wFileName> and quit
                    Example: Resource /r=typical.ini /w=typical.asm

            e     Program EEPROM from (rFileName) and quit
                    Example: Resource /r=typical.ini /e

------------------------------------------------------------------------------
COMMANDS:
---------------
When RESOURCE is run with no command line parameters, the program lists the 
    help menu and allows individual commands to be entered. The following 
    commands are available from inside the program. Commands are case 
    insensitive and are one character - NO RETURN 

A - Indicates, and allows the setting of the CONTROL Logical Device, 2, 
    address. The default for data entered is decimal, with hex data beginning 
    with '0x'. This command tells the program where to look for the CONTROL
    Logical Device. 

<alt> A - Forces the CS4232 to the address given. This command uses the 
    Crystal Key to force the CONTROL Logical Device, 2 to the address given. 
    The down side is that if any other software needed the CONTROL logical 
    device, it would not be able to find it. 

C - Check Data. Checks data read in for validity and gives user option to fix 
    data. (NOT IMPLEMENTED YET) 

<alt> C - Checks data for errors and automatically fixes errors without user 
    intervention. (NOT IMPLEMENTED YET)

D - Disassemble data. Disassemble data into an .ASM formatted file format 
    (similar to file in Appendix A of the CS4232 Data Sheet) and display on 
    the screen. Comments help in debugging PnP or Hardware resource data.
    
E - eeprom read. Read the eeprom located through the CONTROL Logical Device 
    address space. If all data = 0xFF, the eeprom is not programmed or non-
    existent. 

<alt> E - Write eeprom with data previously loaded from a file. Then verify 
    the eeprom data. 

H or ? - Help Screen. Lists the valid commands. Shown later in this document. 
    Also lists the program name, version number, and date compiled. The help 
    screen is automatically shown when the program is started if no command 
    line parameters are given. 

I - Read CS4232 internal device data. Starts reading at 0x2090 in the CS4232 
    internal RAM space. 

P - Print the current data to the screen in hex and ascii format. The left 
    side of the screen lists the address, in hex, followed by a ':'. Then 
    followed by 16 hex bytes, followed by 16 ascii characters delimited by '|' 
    characters. Unprintable characters are listed as '.'. Example:
         TEST256.DAT        Size = 225 (0xE1)
    000: 55 AA 00 DD 00 48 75 B9   FC 10 03 00 00 00 00 00   |U....Hu.........|
    010: 00 00 00 00 0A 10 00 82   1A 00 43 72 79 73 74 61   |..........Crysta|

Q - Quit program. Return to DOS

R - Read File. The file extension, which is required, determines the format of 
    the data read in. The following file formats are supported:

 .ASM - hex data starting with 'DB' with all hex data starting with '0' as 
    follows: 03fH. ASCII is also supported when enclosed in single quotes as 
    follows: 'MPU401'. Comments started with ';' character.

 .BIN - binary file. no comments, data only, in binary form.

 .C - C programming language include file. Appears as an unsigned char 
    array. Data is in hex format, as 0x3f. Data is not started until open 
    braces '{' is found. 

 .HEX - ASCII, 2 Hex digits per line defining one byte.

 .INI - The most user friendly input file format. Only add the variables 
    needed. Defaults are used throughout. Will add all extraneous data needed. 
    The variables needed are described in the INI FILE section below.

V - Verify eeprom data against data from previous file loaded.

W - Write file. The file extension, which is required, determines the format 
    of the data written into the file. The following file formats are 
    supported:

 .ASM - hex data starting with 'DB' with all hex data starting with '0' as 
    follows: 03fH. ASCII is also supported when enclosed in single quotes as 
    follows: 'MPU401'. Comments started with ';' character. Similar to the 'D' 
    command screen output. Normally used as part of a hostload assembly 
    program.

 .BIN - binary file. no comments, data only in binary form. Normally used to 
    program EEPROMs externally - from an EEPROM programmer. (The other method 
    is to program the EEPROM through the CS4232 - <Alt-E> command.)

 .C - C programming language include file. Appears as an unsigned char 
    array. Data is in hex format, as 0x3f. Normally used as part of a hostload 
    C program.

 .HEX - ASCII, 2 Hex digits per line - defining one byte. This file is useful 
    for custom programs that want to read a very simple file. The file has no 
    comments.

 .PRN - Hex dump. Prints hex data with ASCII on the right side. Similar to 
    output from the 'P' command in the program. 
------------------------------------------------------------------------------
HELP SCREEN:
-----------
The following is seen when RESOURCE is run with no command line parameters:

CrystalWare(tm) RESOURCE  Version 1.95  9/12/95
Copyright(c) 1995 Crystal Semiconductor Corp. All Rights Reserved.


                                COMMANDS                
                ----------------------------------------
                A - CONTROL Logical Device Address     
          <alt> A - Force CONTROL Logical Device Address
                D - Disassemble Data       
                E - EEPROM Read        
          <alt> E - Write & Verify EEPROM
                H - Help (This Screen) 
                I - Read Internal CS4232 IC Data    
                P - Hex Screen Print   
                Q - QUIT Program       
                R -q Read File         
                V - Verify EEPROM      
                W - Write File        

Command>
------------------------------------------------------------------------------
INI FILE:
---------
The following is a list of the pertinent in file variables. The hardware 
    resource data, if present, MUST be included before any logical device 
    data. The variables are case insensitive. ALL HARDWARE RESOURCE DATA HAS 
    DEFAULTS. Since the CS4232 does not allow modification of most the 
    Hardware resource data, it is strongly recommended that the hardware 
    resource data not be included in the .INI file - let the defaults take 
    over. Comments are started with a ';'. See the TYPICAL.INI for file 
    example. 

GLOBAL VARIABLES: Global variables must come before logical devices. The 
    example line gives the default value if not included in file.

 IODecodeBits - States whether 16 bit or 10 bit address decoding is used.
                Set to 16 if CS4232 SA12-SA15 pins are connected
    Possible values: 10, 16
    Example: IODecodeBits = 10

 DataType     - Describes the type of data to support; either EEPROM or 
                Hostload. This data is used when using the W - Write command.
                EEPROM data starts with 0x55, 0xAA, size. Hostload doesn't
                Hostload data swaps the order of Mixer and Peripheral Port 
                Length bytes.
    Possible values: Eeprom, Hostload
    Example: DataType = Eeprom

    
HARDWARE RESOURCE DATA: Must come before logical devices. The example gives 
    the default value if not included in file.
    
 PeripheralPortLength - Determines the I/O size of the peripheral port.
                Determines the function of CS4232 pin XCTL0/XA2. 
    Possible values: 4, 8
    Example: PeripheralPortLength = 4

 PossibleIRQ - Interrupts on CS4232 IRQ pins A-F, in order. Values can be 
               separated by spaces or commas, must have 6 values, and can be
               entered as decimal or hex (No '0x' for hex). 
               The CS4232 does not allow changing these values
    Example: PossibleIRQ = 5 7 9 11 12 15

 PossibleDMA - DMAs on CS4232 DMA/DACK pins A-C, in order. Values can be 
               separated by spaces or commas, and must have 3 values.
               The CS4232 does not allow changing these values
    Example: PossibleDMA = 0 1 3
    
PnP RESOURCE DATA: Must come before logical devices. 

 SerialNumber - PnP Isolation Serial Number. Should be modified by OEM to 
                distinguish their card from others using the CS4232. Can be 
                entered as decimal or hex - hex starts with '0x'.
    Example: SerialNumber = 0xFFFFFFFF
    
 OemId - Sets the Crystal-supplied OEM ID in the vendor ID. Must be used to 
         distinguish each OEM's card uniquely. Must have a unique number per
         card type. Contact Crystal to get OEM IDs. The number is in hex.
    Example: OemId = A0         ; Therefore Vendor ID = CSCA032

 DeviceName - Ansi ID for Card/Device. 
    Example: DeviceName = CS4232

 PnpVersion - PnP Specification Version Number
    Example: PnpVersion = 1.0

 VendorVersion - Vendor Version number
    Example: VendorVersion = 0.1

----------------------------
As previously mentioned, all values above must come before starting the actual 
    logical device variables. Logical devices are entered in the order 
    listed. Some systems may not work if logical device numbers are skipped or 
    listed out of order. Logical Device numbers start with 0. Although DMA and 
    IRQ values are located within physical devices, they are really associated 
    with logical devices. A logical device consist of up to (maximum):
        Logical device number (0-?)
        Logical device name (Ansi ID)
        2 DMAs: Dma or DmaPlay or Dma0
                Dma1 or DmaCapture
        2 IRQs: Irq or Irq0
                Irq1
        3 Physical Devices (see Physical Device description below)
    
 [LD#]  - All logical devices must start with this variable. # must be 
          replaced with the logical device number.
    Example: [LD0]     

 Name   - All logical devices should have an Ansi Name. Ansi names can include 
          spaces.
    Example: Name = WSS/OPL/SB

 LogicalID - Resets the default Logical ID. Format must be 3 ASCII characters
                followed by 4 hex digits - per PnP spec. One is allowed per
                logical device and replaces the default of CSC000x, where x
                is the Logical device number. The default for the example 
                would be CSC0001. 
    Example: LogicalID = PNPB02F     ; Game Compatible ID

 Choice - The Choice option allows specifying multiple choices for a logical 
          device configuration. When using multiple choices for a logical 
          device, each choice MUST start with a 'Choice' variable; 
          followed by the physical device data (includes DMA and IRQ values).
          The Default option generates a 0x30 PnP structure instead of 0x31. 
    Possible values: Best, Acceptable, Suboptimal, Default
    Example: Choice = Acceptable

Physical devices exist in side logical devices. This program supports up to 3 
    physical devices within a logical device. DMAs and IRQs are considered 
    part of the physical device in that they start with the physical device 
    name. A physical device consist of:
        Physical Device Name (part of each variable listed below) Maximum 
        Base or BaseStart/BaseEnd
        Align
        Length
        IoBits
        CompatibleID
    NOTE: The 0.8 revision and beyond allows the Align, Length, and IoBits to 
    cross the "Choice" variable. Therefore, only one of each is needed per 
    logical device.

 Physical Device Name - NOT A VARIABLE BY ITSELF - Prefix to variables below. 
        Maximum character length looked at is 4. Anything over 4 characters is 
        ignored. Anytime the physical device name doesn't match, a new 
        physical device is assumed. Although this program doesn't care about 
        the order of physical devices, the CS4232 does. The CS4232 requires 
        the physical device order in logical device 0 matches the data sheet.

 Base - Defines the named physical device I/O base minimum and maximum base 
        address, in hex only
    Example: WssBase = 534              ; WSSbase = 534 to 534 hex.

 BaseStart - Defines the named physical device I/O base minimum base address,
             in hex only. Requires a 'BaseEnd' variable.
    Example: WssBaseStart = 0            ; WSSbase minimum address is 0

 BaseEnd - Defines the named physical device I/O base minimum base address,
           in hex only. The BaseStart default is 0 if not given
    Example: WssBaseEnd = FFC            ; WSSbase maximum allowable address 

 Align   - Defines the PnP Alignment. Accepts dec or hex (hex starts with 
           '0x'). Must be included with Base address if not in default list 
           below.
    Example: WssAlign = 4

 Length  - Defines the PnP Length. Accepts dec or hex (hex starts with '0x').
           Must be included with Base address if not in default list below.
    Example: WssLength = 4

 IoBits  - OPTIONAL - Normally not included. Overrides internal defaults and 
           IODecodeBits variable.
    Possible values: 10, 16
    Example: WssIoBits = 10

 CompatibleID - Allows one PnP compatible ID per physical device. Can 
                be used to include Compatible ID's or override defaults. Value
                of 0 forces the compatible ID off. Format must be 3 ASCII 
                characters followed by 4 hex digits - per PnP spec.
    Example: GameCompatibleID = PNPB02F     ; Game Compatible ID


NOTE: The following physical device names have defaults associated with them. 
    The defaults can be overridden by including the appropriate variable 
    above.

    Wss - Windows Sound System defaults:
        WssAlign = 4
        WssLength = 4

    Syn - Synthesis
        SynAlign = 8
        SynLength = 4

    Sb - Sound Blaster Pro Compatible
        SbAlign = 16
        SbLength = 16

    Game - Game Port (ie. Joystick)
        GameAlign = 8
        GameLength = 8

    Mpu - MPU-401
        MpuAlign = 2
        MpuLength = 2

    Ctrl - Control Logical Device
        CtrlAlign = 8
        CtrlLength = 8


The following is an example of logical device 0 and logical device 1:
    [LD0]
    Name = WSS/OLP/SB

    WssDmaPlay = 0 1            ; DMA0: Shared by Wss and SBPro devices
    WssDmaCapture = 1 3         ; DMA1: Wss Capture only - Full Duplex support
    WssIrq = 5 7 9              ; IRQ0: Shared by Wss and SBPro devices
    WssBaseStart = 100          ; BASE0: Wss I/O Base Address minimum - in hex.
    WssBaseEnd = 534            ; BASE0: Wss I/O Base Address maximum - in hex.
    SynBase = 388               ; BASE1: Synthesis I/O Base min. and max
    SynIrq = 11                 ; IRQ1: Synthesis Interrupt
    SbBaseStart = 220           ; BASE2: SBPro I/O Base Address minimum
    SbBaseEnd = 240             ; BASE2: SBPro I/O Base Address maximum
    SbAlign = 32                ; Force Alignment: 220 or 240 addresses only

    WssCompatibleID = PNPB007   ; PnP compatible ID

    [LD1]
    LogicalID = PNPB02F         ; replace default with PnP ID
    Name = Game

    GameBaseStart = 200         ; Game I/O Base Address minimum - in hex.
    GameBaseEnd = 3F8           ; Game I/O Base Address maximum - in hex.

------------------------------------------------------------------------------
EXIT CODES: 
----------
When this program is run with the switch /d=off, the program uses exit codes 
to indicate a problem occurred. The following is a list of exit codes. A good 
example is the following production line batch file:
    @ECHO OFF
    ECHO Programming the EEPROM . . . 
    resource /d=off /f=0x120 /r=typical.ini /e 
    IF ERRORLEVEL 2 GOTO FAILED
    IF ERRORLEVEL 1 GOTO NO_PART
    ECHO EEPROM programmed successfully !
    REM continue with testing . . .
    GOTO EXIT
    :NO_PART
    ECHO CONTROL logical device not found
    GOTO EXIT
    :FAILED
    ECHO Programming EEPROM failed
    :EXIT


0 - Exit normal, everything okay

1 - Cannot find CONTROL logical device (#2) at address given 
    Therefore, can't access CS4232 internal RAM or EEPROM
2 - eeprom data did not match file data - verify error
3 - Could not open file 
4 - Data not defined yet. Cannot execute command asked for
6 - Disassembly errors
8 - EEPROM read size is greater than allowed (512)
9 - EEPROM data read is invalid (didn't start with 0x55, 0xAA). 
    EEPROM is not programmed or non-existent.
------------------------------------------------------------------------------
HISTORY: Additions/changes between 1.90 and 1.95
----------
1. Reading .INI files
    a. SynAlign default is now 8 (was 4)
    b. MpuAlign default is now 2 (was 8)
    c. WssIoBits and CtrlIoBits default to the global IODecodeBits variable
        (used to default to 16 bits)
    d. New Choice option: Choice = Default (generates 0x30 instead of 0x31)
    e. New Logical device variable: LogicalId. See Text
    f. New OemId variable in PnP resource data. Sets part of the Vendor ID 
        to the OEM's unique number.
    g. There are no default CompatibleIDs - they must be explicitly specified
        The old ones were:  WssCompatibleID =  PNPB007
                            SynCompatibleID =  PNPB020
                            SbCompatibleID =   PNPB002
                            GameCompatibleID = PNPB02F
                            SbCompatibleID =   PNPB006
