*********************
** 2-Mar-1998 **
*** Version 4.05 ***
***************************
Note the last changes in SROMPROD that are detailed in the SROMPROD
section!!
Supporting the Digital Semiconductor 21140, 21140A, 21041, 21142,
21143 (including 21143 Rev 4.0, Rev 4.1) and 21540 (rev 4.8 and rev 4.9)
SROM specification version 4.05.
SROM programming utilities
--------------------------
Included in this kit are two utilities that enable users to modify the
serial ROMs on their DS21041, DS21140, DS21142, DS21143 and DS21540 based
network cards.
These utilities support the Magic Packet functionalities.
Magic Packet is a trademark of Advanced Micro Devices, Inc.
The utilities also support a 4K SROM (8 bits address).
Programs:
---------
1. SROMPROD.EXE - Program to blast SROMs in the present format with the
address block specified by the user, or to dump the
contents of the SROM into the file specified by the user.
This program can be used on all 21x4 adapters.
2. SROMUTIL.EXE - Program to create template files in the new format
(which are necessary for use with the other two
utilities) and to view the contents of existing SROMs
in the new format.
SROMPROD program
----------------
The SROMPROD utility programs the SROMs for any Digital Semiconductor
21x4-based networking card.
In order to run the program, you need to have the following updated files:
ADDR.MAX
ADDR.LOG
EB41.TXT, EB41.TOP (for DS21041 based network cards)
EB140.TXT, EB140.TOP (for DS21140 based network cards)
EB140NAT.TXT, EB140NAT.TOP (for DS21140 based network cards, with Natinal MII Phy)
EB140BRD.TXT, EB140BRD.TOP (for DS21140 based network cards, with Broadcom MII Phy)
EB140DC.TXT, EB140DC.TOP (for DS21140 based network cards, with dual connector)
EB140SC.TXT, EB140SC.TOP (for DS21140 based network cards, with single connector)
EB142NAT.TXT, EB142NAT.TOP (for DS21142 based network cards, with National MII Phy)
EB143NAT.TXT, EB143NAT.TOP (for DS21143 based network cards, with National MII Phy)
EB143ML.TXT, EB143ML.TOP (for DS21143 based network cards, with MicroLinear MII Phy)
EB143QSI.TXT, EB143QSI.TOP (for DS21143 based network cards, with QSI SYM Phy)
QSIMAGIC.TXT, QSIMAGIC.TOP (for DS21143 based network cards, with QSI SYM Phy and
Magic Packet information block)
DCS20_10.TXT, DCS20_10.TOP (for DS21143 Rev 4.1 based CardBUS with a 4K SROM
including reset sequence - block type 5,
and GPR sequence for phy power down - block type 6).
GRN40_1K.TXT, GRN40_1K.TOP (for DS21143 Rev 4.0 based network cards with a 1K SROM).
GRN40_4K.TXT, GRN40_4k.TOP (for DS21143 Rev 4.0 based network cards with a 4K SROM).
GRN41_1K.TXT, GRN41_1k.TOP (for DS21143 Rev 4.1 based network cards with a 1K SROM).
GRN41_4K.TXT, GRN41_4K.TOP (for DS21143 Rev 4.1 based network cards with a 4K SROM).
GRN48_4K.TXT, GRN48_4K.TOP (for DS21143 Rev 4.8 based network cards with a 4K SROM).
GRN49_4K.TXT, GRN49_4K.TOP (for DS21143 Rev 4.9 based network cards with a 4K SROM).
These files are templates samples and can be replaced.
The ADDR.MAX file is a text file containing the last possible address
that SROMPROD will allow the user to program.
The ADDR.LOG file is a file containing the address to be written. This
address will be automatically incremented by one bafter SROMPROD programs
the adapter.
Thus the ADDR.LOG should be initially created with the first address
to be written. Whenever SROMPROD runs, it uses ADDR.LOG to get the
address to be programmed, then it programs the SROM of
the present network card with this IEEE address (provided that it is
within the range allowed by ADDR.MAX).
If SROMPROD is run in a directory where there is no ADDR.LOG file,
SROMPROD will prompt the user for the first IEEE address to be used, and
will create the ADDR.LOG file accordingly.
IMPORTANT: The ADDR.LOG and ADDR.MAX files supplied in this kit
are just a sample files and should be treated accordingly.
The command line syntax is :
SROMPROD [SROM=First SROM index] [template=Template File Name]
[/nolog] [/map] [cfid=New CFID]
[/dump[=index of SROM to read] dumpfile=File Name]
[/ignoreCRC] [noCRC]
[/magic_format [/magic_ieee=
|"self"|]
[/magic_cmd=]]
[/ethernet_tuples= [/modem_tuples=]]
[/token_format]
NOTE: for versions 3.01.1 and later, the program's command-line parsing
is not case sensitive.
i.e., "sromprod srom=1 /ignorecrc" is an acceptable command line,
as is (and was) "sromprod SROM=1 /ignoreCRC".
Command line qualifiers:
SROM=First SROM index (optional)
The SROM index is the index of the SROM to be written. If there
is only ONE networking card in the machine, this parameter is
unnecessary. This number is NOT the PCI device number, but an
index (i.e. 1 or 2 or 3 ...) which specifies the order the
devices were found on the machine.
The numbering scheme for this index can be obtained by using
the '/map' flag.
If this parameter is not specified it will be taken as 1.
template=Template File Name (optional)
Can be used to give a specific template file name to use when
programming the SROMs. File must have a correct CRC, and can be
created using the SROMUTIL program.
/nolog (optional)
Every SROM write operation is logged in a file called log.txt.
Logging can be disabled using this keyword.
/map (optional)
Displays the list of SROMs in the machine with their indexes.
cfid=New CFID
Allows program to recognize devices with CFIDs different from the
ones recognized by default. The following devices are recognized by
default: 21041, 21140, 21140A, 21142, 21143 and 21540.
Example: SROMPROD template=mysrom.txt cfid=0099
NOTE: It is the user responsibility when he programs an SROM
with an unsupported CFID, since it may cause incompatibilities.
/dump (optional)
Reads the contents of the SROM from the device, into the file
specified by File Name. If there is more than one SROM in the machine,
the SROM index should be specified. If the dumpfile=File Name flag
isn't used, the user is prompted for the file name.
This flag is useful when the SROM is corrupted and SROMUTIL wouldn't
load it. In this case the only way to view the SROM is by dumping it
into a file using this flag.
/ignoreCRC (optional)
If used, the program will not reject a template file with an
illegal CRC, and will write the template file to the SROM with a
legal CRC, calculated at run-time.
noCRC (optional) - special engineering option.
Disables recalculation of the CRC for a template file written to
the SROM. In this case, the CRC in the file will be used, almost
always resulting in an erroneous CRC - and thus, in an illegal
SROM image.
When used, the program will not reject files with illegal CRCs.
(Therefore, there is no need to use the "/ignoreCRC" option when
this option is used.)
The IEEE address will be written as usual.
NOTE : SROMs with illegal CRCs (but of legal length) can be
produced this way.
/magic_format - will calculate the SROM CRC on bytes 0:95, and a CRC8
on the last 32 bytes of the template.
/magic_cmd= - places the given value in the SROM Magic Packet command field.
/magic_format must be given first.
This flag is optional. Not using it will use the
magic_cmd word that is in the specified template.
/magic_ieee=xx-xx-xx-xx-xx-xx
/magic_ieee=self
/magic_ieee=template
Controls what value is placed in the MAGIC IEEE address field.
/magic_format must be given first.
If /magic_format is specified and this key is not, the board's
IEEE address is placed in the MAGIC IEEE field.
If an address is given, that is what is placed in the MAGIC IEEE
field.
If the word "self" is given, the board's IEEE address will be used
also as the MAGIC IEEE address.
If 'template' is specified, the contents of the template in the
MAGIC IEEE address field is not overwritten (neither by the
board's address, nor by any other data).
/ethernet_tuples=
Will place the ethernet tuples specified in in the offset
in SROM. The offset is calculated from the CIS Low Pointer field
in the the ID Block. If a template is also specified in the command
line the CIS Pointer will be taken from that template, otherwise
it will be taken from the template that is programmed in the SROM.
/modem_tuples=
Will place the modem tuples specified in in the offset
in SROM. The offset is calculated from the CIS High Pointer field
in the the ID Block. If a template is also specified in the command
line the CIS Pointer will be taken from that template, otherwise
it will be taken from the template that is programmed in the SROM.
If this flag is specified, the "/ethernet_tuples=" must
also be specified in the command line.
/token_format
This flag should be used when the addresses in the ADDR.LOG and
ADDR.MAX files are in a Token Ring format.
In this case the range of the address will be checked on the token
ring format address, but the address in the ADDR.LOG file will be
converted to the IEEE address format and of course will be programmed
to the SROM in the IEEE format.
When SROMPROD is executed, it identifies the first chip associated with
the specified SROM index (specified either by the /dump= or by the SROM=
flag); then, if the /dump flag wasn't used, SROMPROD programs the SROM
according to the format found in the specified template file.
Next it goes through all the other SROMs on the machine (serially,
according to index numbers), and writes their SROMs with IEEE addresses
sequential to the first address.
If an SROM to be written to is in a known format, the program will warn
the user of it, asking whether or not to overwrite it.
In the case of the SROM being of the new (128-byte or 512-byte) format,
after the program confirms the user's wish to overwrite the SROM, the user
will be given an option to leave the SROM's IEEE address unchanged - that is,
to use the same address when overwriting the SROM's contents.
If the /dump flag was used, the program reads the contents of the SROM (if
there is more than one SROM in the machine, the index of the desired SROM
must be specified), and writes them to the specified file. If the user did
not enter a file name at the command line, the file name is prompted for.
If an illegal CRC is found on the SROM, the program will also give a
message.
There are some more templates attached that you can use to program the
SROM, but before you use any of them make sure you use the right one.
Each template (*.txt file) has a matching topology file (*.top) so you
will be able to load the template using the SROMUTIL tool.
The templates are:
EB41.TXT (for DS21041 based network cards)
EB140.TXT (for DS21140 based network cards)
EB140NAT.TXT (for DS21140 based network cards, with Natinal MII Phy)
EB140BRD.TXT (for DS21140 based network cards, with Broadcom MII Phy)
EB140DC.TXT (for DS21140 based network cards, with dual connector)
EB140SC.TXT (for DS21140 based network cards, with single connector)
EB142NAT.TXT (for DS21142 based network cards, with National MII Phy)
EB143NAT.TXT (for DS21143 based network cards, with National MII Phy)
EB143ML.TXT (for DS21143 based network cards, with MicroLinear MII Phy)
EB143QSI.TXT (for DS21143 based network cards, with QSI SYM Phy)
QSIMAGIC.TXT (for DS21143 based network cards, with QSI SYM Phy and
Magic Packet information block)
DCS20_10.TXT (for DS21143 Rev 4.1 based CardBUS with a 4K SROM
including reset sequence - block type 5,
and GPR sequence for phy power down - block type 6).
GRN40_1K.TXT (for DS21143 Rev 4.0 based network cards with a 1K SROM).
GRN40_4K.TXT (for DS21143 Rev 4.0 based network cards with a 4K SROM).
GRN41_1K.TXT (for DS21143 Rev 4.1 based network cards with a 1K SROM).
GRN41_4K.TXT (for DS21143 Rev 4.1 based network cards with a 4K SROM).
GRN48_4K.TXT (for DS21143 Rev 4.8 based network cards with a 4K SROM).
GRN49_4K.TXT (for DS21143 Rev 4.9 based network cards with a 4K SROM).
Note that the some of the above templates enable you to use SROMPROD for programming
the appropriate board with magic info block.
To program the board with this template and have the magic information you need to
run SROMPROD using the following command line:
sromprod template=QSIMAGIC.TXT /magic_format
Note, that unlike previous versions, you will not need to use the /magic_ieee and
/magic_cmd flags, since SROMUTIL already supports Magic Information Block.
So, if you programmed a template with Magic Information Block using SROMUTIL,
you only need the /magic_format flag with SROMPROD (with 'template=' flag, of
course) so the two CRC's will be calculated correctly (the regular CRC on bytes
0:95 and CRC8 on the 32 bytes of the Magic Block).
Also note that the board IEEE address and Magic IEEE address in these templates
are for a specific board.
The board IEEE address can be changed when programming an SROM using SROMPROD
(answer YES to the question: "would you like the board to keep its IEEE address?").
The Magic IEEE address can be changed using SROMUTIL. If you want the Magic IEEE address
to be the same as the board IEEE address, you don't have to remember it. Leaving
the DataLine of the Magic IEEE address empty will make the MAgic IEEE address the same
as the board's IEEE address.
NOTE: It is possible, although not recommended to program one device with another
device's template.
What you need to do to make this possible is to edit the .top file to
contain the correct ID and revision of the device you wish to program.
(The .top file is a regular text file.)
You have to pay attention to the fact that since some devices have the
same ID but a different revision, the .top file contains four digits
which are the logical OR of the ID and revision of the device (only if
there are several devices that have the same ID). For example:
for the device with the ID 0019 and the revision 4.1 (21143 Rev 4.1)
the .top file contains 4119.
If you edit the .top file pay attention to do it exactly in this format.
Also note that if you make such an edition it is your own responsibility,
since different devices usually support different functionalities.
Thus, although less convenient, it is better creating a new template for
the different device using SROMUTIL. This way the correct .top file is
created automatically when you save the template youu created.
NOTE: These are the main changes done in SROMPROD Version 3.06:
1. The address in the ADDR.LOG file is from now on the first address
to be programmed and not the last address that was programmed.
Thus, the user needs to wrote to that file the first address he
wishes to program (and not the first address minus one, as it was
until today).
2. When programming a multiple device SROM, that is, an SROM that
has more than one device attached to it, the address in the
ADDR.LOG file will be incremented by the number of devices
attached to this SROM (and not defaultly by one, as it was
until today).
This number of devices is taken from the ControllerCount field
in the SROM template that the user wishes to program.
SROMUTIL program
----------------
The SROMUTIL program is used to create template files for the new SROM
format.
The program can also display the data obtained from parsing an SROM
on a given device (i.e IEEE address, Media data, Register data etc.).
The command line syntax is :
SROMUTIL [/engineering]
Command line qualifiers:
/engineering
This qualifier enables some features that do not appear in
regular execution.
There are two menus to choose from :
1. FILE - This menu contains the following items:
a. Save Data (Engineering mode only)
Saves the data currently displayed on the screen in a template
file that can be used by SROMPROD.
This will cause two files to be created:
One file has the name given by the user. It contains the
byte-map of the SROM.
The name of the other companion file is based on the name given
by the user -- it has the suffix "top" which stands for
topology (i.e. if the user gives data.txt; this file is data.top).
This file contains a list of the device IDs of the adapters
sharing this SROM. It is necessary in order to correctly parse
the device information fields correctly.
b. Save SROM
Save the exact hex dump of the currently chosen SROM (chosen
using Read Device command) to a file.
c. Load (Engineering mode only)
Loads a file previously saved by the utility. This file must
be a valid template file and it's companion topology file must
exist in the same directory. The data obtained by parsing the
file will be displayed on the screen. The user can change this
data and save it again. It is necessary to have the topology
in the same directory.
d. Quit
Exit to DOS.
2. SROM - This menu contains the following items:
a. Read Device
This option displays a list of SROMs of DS21041, DS21140, DS21142,
or DS21143 devices SROMs found on the machine. The user
can choose one of the devices (using a double-click, ENTER or SPACE).
The data obtained from that device's SROM will then be displayed.
This data can be changed and/or saved into a template file.
b. Create Template (Engineering mode only)
This option enables the user to create a completely new
template file.
In addition to the single-device, single-SROM configuration, it
also supports creating template file for a single SROM shared
by multiple devices. The user can define the devices that will
be sharing the SROM and change the data for each adapter.
The main window will contain a list of the adapters currently
defined for this SROM (initially this list will be empty).
Items can be added to or deleted from this list.
Choosing an item will display the data for that adapter for
editing.
The user can also fill the SROM's Sub-system Vendor ID field,
and Sub-system ID field, if desired (See the HRM to know if
these fields are applicable for your chip).
The user can also fill the SROM's Cardbus CIS pointer fields
(ROM Image and Address Space Offset are supported). This can
be done only if the Sub-system Vendor ID and Sub-system ID
were filled (See the HRM to know if these field are applicable
for your chip).
It is also possible for the user to enter Magic Packet Information
Block, that is: Magic IEEE Address and Magic Command. The user can
enter the two of them, or none. If none of them was entered, it is
assumed that the template has no Magic Block. It possible not to
enter the Magic IEEE address, but then the board's IEEE address will
be taken also as the Magic IEEE address.
NOTE for two things:
1. Entering zeros is not the same as leaving these fields empty!
Entering zeros means that the Magic IEEE Address is zeros. Leaving
the Magic IEEE Address empty will take the board's IEEE address
to be also the Magic IEEE Address.
2. The Magic IEEE Address has 6 bytes. So, if the user enters an odd
number of digits, the last one will be casted into a full byte
(for example: 123 will become 1203).
Also, if the user didn't enter 6 bytes, the missing ones (LSB)
will be zeros (for example: 11223344 will become 112233440000).
The Magic Command is a word, so if less than four digits are entered,
the command will be casted into a full word (for example: 112 will
become 0112).
c. Byte map (Engineering mode only)
Display the hex dump of the SROM on the screen.
d. Write (Engineering mode only)
If an SROM was read using the "Read Device" command and the
data on the screen was changed by the user, this command will
write the modified data into the SROM.
It is recommended to write data to the SROM using SROMPROD and not to
use this menu option of SROMUTIL, because the checks for correctness
are much more comprehensive in SROMPROD (since SROMPROD was designed
mainly for programming SROMs).
Data display :
--------------
If the Sub-system Vendor ID and Sub-system ID are supported on the SROM,
this information can be displayed or changed by selecting the ID Block
button.
If the Cardbus CIS Pointer is supported on the SROM, the information can
be displayed or changed by selecting the ID Block button, and then
selecting the CardBus button.
The data parsed from the SROM is displayed using four types of display
windows.
1. The "Adapters Sharing ROM" window.
This window will contain the IEEE address for the SROM and the list of
all adapters sharing the SROM. Choosing an item from this list will
display the "Adapter Info" for that adapter.
2. The "Adapter Info" window.
This window will contain the data fields obtained from the info leaf of
that device's SROM. Information displayed includes selected connection
type, and a list of the media types defined for this adapter. Choosing
an item from the media list will display the "Media data" for the
selected media.
3. The "Media data" window.
This will contain medium-specific data obtained from the relevant
media block in the SROM. If the medium is an MII medium, information
about the relevant MII Phy chip will be displayed by selecting the
"Phy Info" button.
NOTE: If an MII medium is specified to be Nway Advertised Only, no phy
information will appear, since it is not in the Media Capabilities
of the MII Phy chip.
4. The "Phy info" window.
This will contain information about the phy chip, that is not related
to the media supported by it: i.e., the Reset and GPR sequences.
The Reset sequence (Hardware reset of the Phy) is executed by the
DC21x4 drivers each time the PHY is Initialized. The GPR sequence is
executed each time the MAC speed or media changes.
5. The "Reset Sequence" window.
This will contain the Reset Sequence, which indicates how external chips
are reset via the General Purpose Register.
(See the HRM to know if these field are applicable for your chip.)
6. The "Phy Shut Down" window.
This will contain the GPR Sequence to be written to the General Purpose
Register in order to shut down the phy, when certain situations occur.
(See the HRM to know if these field are applicable for your chip.)
7. The "Command Fields" window.
This will contain check boxes for each bit of CSR6 and is used for
generating the CSR6's mode bits.
(This is applicable only for a 21143 that describes SYM media.)
8. The "Magic Block" window.
This will contain a DataLine for the Magic IEEE Address, on which the
workstation should be woken up. The window will also contain check boxes
for the bits of the Magic Command.
9. The "ID Block" window.
This will always contain the Sub-System Vendor ID and Sub System ID.
It will contain the CIS Pointer fields when CardBUS is supported and the
user wishes to have tuples. The fields of the CIS Pointer will be different,
depending if the tuples are in the BOOT ROM or the SROM.
For the GreenNet there will also be Func0_HwOptions and MiscHwOptions.
If modem is supported, modem information will also be added to this window.
NOTE: The 'escape'/'cancel' mechanism will not undo changes made after
adding a medium or changing medium data. The user must either
quit the present SROM editing session or manually undo the changes
in order for them to be disregarded.
It is recommended to read the SROM format version specification in order
to understand the meaning of the fields displayed. It is included in this
kit as SROM_405.DOC.
It is also recommended to read the documednt SROMSIZE.DOC to understand the
choice of 1K/4K for the templates and the support in ID block and magic block
in some situations.