RESOURCE.TXT 9/19/95 For differences between version 1.97and 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. ------------------------------------------------------------------------------ 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: 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: /= m Minimal IC checks (Disables IC Read Command) a CONTROL Logical Device Address f Force CONTROL Logical Device Address d Display mode h Command line help - this screen (no parms) r Read file Example: Resource /r=typical.ini w Write (rFileName) to 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. 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. 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. 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 - 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.97 9/19/95 Copyright(c) 1995 Crystal Semiconductor Corp. All Rights Reserved. COMMANDS ---------------------------------------- A - CONTROL Logical Device Address A - Force CONTROL Logical Device Address D - Disassemble Data E - EEPROM Read E - Write & Verify EEPROM H - Help (This Screen) I - Read Internal CS4232 IC Data P - Hex Screen Print Q - QUIT Program R - 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 = 8 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.97 ---------- 1. Reading .INI files a. SynAlign default is now 8 (was 4) b. WssIoBits and CtrlIoBits default to the global IODecodeBits variable (used to default to 16 bits) c. New Choice option: Choice = Default (generates 0x30 instead of 0x31) d. New Logical device variable: LogicalId. See Text e. New OemId variable in PnP resource data. Sets part of the Vendor ID to the OEM's unique number. f. There are no default CompatibleIDs - they must be explicitly specified The old ones were: WssCompatibleID = PNPB007 SynCompatibleID = PNPB020 SbCompatibleID = PNPB002 GameCompatibleID = PNPB02F SbCompatibleID = PNPB006