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
