
                            Broadcom Corporation
                            16215 Alton Parkway
                           Irvine, CA 92619-7013
              
                               Readme.txt
                              
                Broadcom NetXtreme Firmware Upgrade Tool
                                 for Windows
                         
                Copyright (c) 2000-2006 Broadcom Corporation
                            All rights reserved.
                              December 8, 2006


Table of Contents
=================
    1. Introduction
    2. Requirements
    3. Installation
    4. Command Usage
    5. Exit Codes
    6. Examples 
    7. Scope 
    8. Disclaimer

1. Introduction:
================

This utility is a console application. Users could run it from a Windows 
command prompt. The application will use the console and interact with 
users.

When calling the utility from another process or when using the utility 
as a command line tool, the utility will take command from parameters 
return appropriate exit code to indicate result of the command. 

This module is dependent on device driver and BMAPI module 
for firmware access.

If the calling process do not want Windows to pop up a console window, 
it could use Windows API to make OS not to pop up the console window. 
For example, the calling process could use 'CREATE_NO_WINDOW' 
flag in CreateProcess() API when create the process.


2. Requirements:
================

     1.  Driver version 3.28.0 or above.

     2.  BMAPI version 7.5.12 or above.


3. Installation:
================

     1.  On a system with NetXtreme family of NICs, install the 
         driver package using the installer.

     2.  Copy BMAPI binary (dll) to the same location as winfwupg.exe.
     

         
4. Command Usage:
=================
  
Usage:
  winfwupg { -all | [service_name | MAC] } [Commands]
    The '-all' option applies to 'upgrade' and 'restorenvram' commands
    only. 

    1. When '-all' is specified, 'service_name' or 'MAC' cannot be 
       specified. Both 'upgrade' and 'restorenvram' commands will use the
       device information in the image to apply to all NICs that match the
       same device ID. 

    2. On Windows, service_name is the service GUID in the form of 
       {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}, 
       e.g.{4D36E972-E325-11CE-BFC1-08002bE10318}. It refers to the series 
       of numbers that Windows uses to identify the adapter.   This can be
       obtained based on the value in the registry NetCfgInstanceId string 
       located at:
       HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Class\{4D36E972-E325-11CE-BFC1-08002BE10318}\####,
       where '####' reflects the enumeration number of the Broadcom adapter. 

    3. 'MAC' is the MAC address name of the NIC in the system. For example, 
       '00:10:18:00:11:99' is a valid MAC address from 'ipconfig' utility. 
       Use '001018001199' as an input parameter to select the NIC.

    Following is the list of available commands:
    help        : list of available commands
    q           : exit the program
    cfg         : Configure NVRAM
    dev         : select an adapter or List available adapters
    dir         : display file directory in NVRAM
    crc         : check/update NVRAM checksum
    dumpnvram   : save entire NVRAM content to a file
    prg         : Program NVRAM with specified firmware image
                  The 'prg' command is designated to facilitate the manufacture operation.
    restorenvram: restore entire NVRAM content from a file
    version     : display version of this program
    upgrade     : upgrades the firmware or bootcode
    -w          : Enable/Disable WOL

    upgrade [-F] {-bc|-mba|-asf|-ipmi|-ump} {<filename>} {<savefile>}
        This command upgrades the firmware or bootcode for
        the NetXtreme controller.  The <filename> specifies
        the name of the file that contains the appropriate image.
        The <savefile> specifies the name of the file to which the
        current NVRAM contents will be saved. 
        Both <filename> and <savefile> are mandatory parameters.
        If the upgrade version is same or older than the version
        in NVRAM, upgrade will be aborted.
        The -F option is to force the upgrade without checking version.
            OPTION           NAME OF FIRMWARE OR BOOT IMAGE
            -bc                bootcode
            -mba               MBA (PXE) code
            -ipmi              IPMI code
            -ump               UMP firmware
            -asf               upgrade ASF

    -w {<value>}
        The function enables or disables WOL settin
        <value> set to '1' to enable WOL.
        <value> set to '0' to disable WOL.

    restorenvram {<filename>} [config [mac]]
        This command reads complete NVRAM image from a file and
        writes the image to NVRAM.
        Before writing the NVRAM image to adapter, verifications
        against source NVRAM image will be performed. If any verification
        failed, the image will not be written to adapter.
        <filename> is the file name of NVRAM image.
        <filename> is a mandatory parameter. 
        'config' means configuration area will copy from source
        image except MAC address.
        Configuration area includes MAC address and various
        options.
        'mac' applies only when 'config' is specified.
        When 'mac' is specified, all configuration are copied
        including MAC address.

    dumpnvram {<filename>}
        Dumps the NVRAM contents to the specified file.
        <filename> is a mandatory parameter. 

    crc 
        Checks the integrity of the NVRAM CRC,

    dir
        Displays a listing of the firmware programmed in NVRAM.

    dev [<number>]
        'number' is the adapter to be selected as target device
  
    prg {-bc} {<new_image>}
        This command programs NVRAM with the specified firmware image.
        -bc        : bootcode
        <new_image>: a mandatory parameter to specify the input binary file.
        Note: 'prg' command only supports 5754/5755/5787 Broadcom adapters.
              The image file for the 'prg' command is required to contain ONLY 
              valid bootcode without other firmware directories.

    cfg {-mac <MAC address to be programmed for current selected device> | 
         -mba <value> | -asf <value> | -ipmi <value> | -ump <value>} 
        This command programs the specified configuration into NVRAM.
        -mac        : <MAC address for current selected device> is a 
                      12-digit HEX MAC address, e.g. 0010181a2b3c.
        -mba        : set <value> to '1' to enable mba firmware.
                      set <value> to '0' to disable mba firmware.
        -asf        : set <value> to '1' to enable asf firmware.
                      set <value> to '0' to disable asf firmware.
        -ipmi       : set <value> to '1' to enable ipmi firmware.
                      set <value> to '0' to disable ipmi firmware.
        -ump        : set <value> to '1' to enable ump firmware.
                      set <value> to '0' to disable ump firmware.

5. Exit Codes:
==============

/////////////////////////////////////////////////////////////////////////
// Return codes
#define FWUPG_OK                                0   // Upgrade firmware OK
#define FWUPG_QUIT                              1   // Quit program
#define FWUPG_PARAM_ERROR                       2   // Not correct parameters
#define FWUPG_NOT_CORRECT_TARGET                3   // Not applicable to this device. 
#define FWUPG_CANNOT_READ_NVRAM                 4   // Cannot read NVRAM
#define FWUPG_FAILED_GET_NVRAM_SIZE             5   // Cannot get NVRAM size
#define FWUPG_CANNOT_GET_HANDLE                 6   // Cannot get NIC handle
#define FWUPG_ADAPTER_NOT_FOUND                 7   // Adapter not found
#define FWUPG_CANNOT_LOCK_ADAPTER               8   // Cannot lock adapter
#define FWUPG_FAILED_GET_PXE_INFO               9   // Failed to get PXE
                                                    // information
#define FWUPG_FAILED_CREATE_NVRAM_IMAGE_FILE    10  // Failed to create NVRAM
                                                    // image file
#define FWUPG_FAILED_WRITE_NVRAM_IMAGE_FILE     11  // Failed to write to
                                                    // NVRAM image file
#define FWUPG_GET_CLOSE_EVENT                   12  // Get close event
#define FWUPG_FAILED_READ_NVRAM_FILE            13  // Failed to read NVRAM
                                                    // image file
#define FWUPG_INIT_FAILED                       14  // Initialization failed
#define FWUPG_UNSUPPORTED_BMAPI_VER             15  // BMAPI is too old
#define FWUPG_NIC_NOT_SUPPORTED                 16  // NIC is not supported
#define FWUPG_UNKNOWN_COMMAND                   17  // Unknown command
#define FWUPG_NVRAM_WRITE_FAILED                18  // NVRAM update failed
#define FWUPG_WRONG_NVRAM_FILE_SIZE             19  // NVRAM image file size
#define FWUPG_NVRAM_IMAGE_CHKSUM_FAILED         20  // NVRAM image file
                                                    // checksum failed
#define FWUPG_NVRAM_CHKSUM_FAILED               21  // NVRAM checksum failed
#define FWUPG_NVRAM_IMAGE_FILE_DEVID_MISMATCH   22  // device information or media 
                                                    // type in NVRAM image file
                                                    // does not match NIC
#define FWUPG_ASF_NOT_SUPPORTED_BY_BOOTCODE     23  // ASF is not supported by
                                                    // the bootcode firmware
#define FWUPG_ASF_NOT_SUPPORTED_BY_NIC          24  // ASF is not supported by
                                                    // the NIC hardware
#define FWUPG_DIR_FULL                          25  // No NVRAM directory entry
                                                    // available
#define FWUPG_INVALID_NVRAM_FILE                26  // Incorrect NVRAM file
                                                    // format
#define FWUPG_NVRAM_FULL                        27  // not enough NVRAM space
#define FWUPG_DIR_NOT_SUPPORTED                 28  // Directory is not
                                                    // supported by bootcode
#define FWUPG_NVRAM_CORRUPTED                   29  // NVRAM corrupted
#define FWUPG_DIR_NOT_FOUND                     30  // a directory entry is
                                                    // not found
#define FWUPG_DIR_UPDATE_FAILED                 31  // Update NVRAM directory
                                                    // failed
#define FWUPG_DIR_FOUND                         32  // a directory entry is
                                                    // found
#define FWUPG_CANNOT_READ_MEM                   33  // Cannot read NIC register
                                                    // or memory
#define FWUPG_MALLOC_ERROR                      34  // memory allocation error
#define FWUPG_FW_IMAGE_WRONG_VERSION            35  // wrong version of
                                                    // firmware image
#define FWUPG_FW_IMAGE_INVALID_ASF              36  // invalid asf image
#define FWUPG_READ_NIC_ASF_TABLE_FAILED         37  // failed to read ASF table
                                                    // from  NIC
#define FWUPG_UNSUPPORTED_NIC_ASF_TABLE         38  // version of ASF table on
                                                    // NIC is not supported
#define FWUPG_REBOOT_FAILED                     39  // unable to reboot machine
#define FWUPG_NOT_SUPPORTED_DRIVER              40  // the version of driver is
                                                    // too old
#define FWUPG_DRIVER_NOT_LOADED                 41  // driver is not loaded
#define FWUPG_FILE_TOO_BIG                      42  // file is too big
#define FWUPG_CANNOT_WRITE_MEM                  43  // Cannot write NIC
                                                    // register or memory
#define FWUPG_MGMT_FW_NOT_FOUND                 44  // Cannot find management 
                                                    // firmware
#define FWUPG_UMP_FOUND                         45  // UMP firmware exist
#define FWUPG_FAILED_TO_GET_VERINFO             46  // failed to get module
                                                    // version info
#define FWUPG_ERR_ENDOFFILE                     47  // unexpected end of file
                                                    // encountered.
#define FWUPG_INVALID_MEDIUM_TYPE               48  // The chip has an unknown
                                                    // medium type. Neither the
                                                    // board is copper nor
                                                    // serdes.
#define FWUPG_INVALID_OFFSET                    49  // invalid NVRAM offset.
#define FWUPG_FILE_ALREADY_EXISTS               50  // output file already
                                                    // exists.
#define FWUPG_NON_SELFBOOT_IMAGE                51  // Not a selfboot image.
#define FWUPG_BAD_MAGIC_VALUE                   52  // Bad magic value
#define FWUPG_BAD_PARITY_VALUE                  53  // Bad parity value
#define FWUPG_BAD_VPD_CHKSUM                    54  // Bad VPD checksum
#define FWUPG_BAD_CHIP_REV                      55  // Bad chip revision
#define FWUPG_VPD_DATA_MISSING                  56  // VPD data missing
#define FWUPG_NO_SELFBOOT                       57  // target not self boot 
                                                    // capable
#define FWUPG_LEGACY_TO_SELFBOOT                58  // Cannot upgrade firmware 
                                                    // from legacy to selfboot.
#define FWUPG_ZERO_SELFBOOT                     59  // upgfrm does not support 
                                                    // Format 0 Selfboot image 
                                                    // upgrade
#define FWUPG_UNSUPPORTED_FEATURE               60  // Feature not supported.
#define FWUPG_DIAG_FAILURE                      61  // diag failure
#define FWUPG_NO_BRCM_ADAPTER                   62  // No Broadcom network 
                                                    // adapter found!
#define FWUPG_FILE_DOES_NOT_EXIST               63  // File does not exist
#define FWUPG_UMP_NOT_SUPPORTED                 64  // ump not supported
#define FWUPG_MISSING_UMP                       65  // UMP config firmware is
                                                    // not loaded in NVRAM
#define FWUPG_CFG_VER_MISMATCH                  66  // UMP config version 
                                                    // mismatch
#define FWUPG_INVALID_ISCSI_IMAGE               67  // invalid ISCSI image
#define FWUPG_INVALID_UMP_IMAGE                 68  // invalid UMP image
#define FWUPG_INVALID_MBA_IMAGE                 69  // invalid MBA image
#define FWUPG_PRG_FAILED                        70  // programming NVRAM failed
#define FWUPG_BOOTSTRAP_UPDATE_FAILED           71  // bootstrap update failed
#define FWUPG_CMD_ALL_NOT_SUPPORTED             72  // '-all' option is not 
                                                    // supported in this context
#define FWUPG_UNSUPPORTED_PLATFORM              73  // Feature not supported on 
                                                    // this platform
#define FWUPG_MAC_PARAM_ERROR                   74  // Cannot override MAC on 
                                                    // multiple NICs.
#define FWUPG_INVALID_BOOTCODE                  75  // Not a valid bootcode file
#define FWUPG_INVALID_IPMI_FILE                 76  // Not a valid ipmi file
#define FWUPG_INVALID_DUMP                      77  // Invalid dump file.
#define FWUPG_INVALID_FORMAT                    78  // Invalid image/file format.
#define FWUPG_DIR_ENTRY_MISMATCH                80  // Mismatch in directory entries
#define FWUPG_MBA_MISMATCH                      81  // MBA directory entry mismatch
#define FWUPG_UMP_MISMATCH                      82  // UMP directory entry mismatch
#define FWUPG_IPMI_MISMATCH                     83  // IPMI directory entry mismatch
#define FWUPG_ISCSI_MISMATCH                    84  // ISCSI directory entry mismatch
#define FWUPG_ASF_MISMATCH                      85  // ASF directory entry mismatch
#define FWUPG_ISCSI_NOT_SUPPORTED               86  // ISCSI is not supported.
#define FWUPG_SPECIAL_UPGRADE_REQUIRED          87  // Special upgrade is required.
#define FWUPG_MISSING_CMD                       88  // No valid command was specified.
#define FWUPG_RESERVE1                          89  // Reserved message holder.
#define FWUPG_RESERVE2                          90  // Reserved message holder.
#define FWUPG_MISSING_ASF                       91  // ASF config firmware is
                                                    // not loaded in NVRAM
#define FWUPG_MISSING_IPMI                      92  // IPMI config firmware is
                                                    // not loaded in NVRAM
#define FWUPG_MISSING_MBA                       93  // MBA config firmware is
                                                    // not loaded in NVRAM
#define FWUPG_NO_DEV_ID                         94  // No device ID in NVRAM image file


6. Examples:
==============
    Note:  
    The 'restorenvram' and 'upgrade' commands shall perform successfully
    for the specified adapter meeting ALL the following conditions:
    1) The device information of the adapter matches that in the image file. 
    2) The adapter currently supports the requested target firmware. 


6.1  Command Line Mode Examples:
*******************************

        'WinFWUpg' will enter interactive mode.

        'WinFwUpg upgrade -bc C:/tmp/new_bootcode c:\\oldBoot' will upgrade 
    bootcode for the ONLY qualified adapter found.  The adapter parameter can 
    be omitted if ONLY ONE qualified adapter is found.

        'WinFwUpg 001018001199 upgrade -mba b57mmbae.nic c:\\backup\\oldPXE.bin'
    will upgrade PXE for the adapter with MAC 00:10:18:00:11:99.

        'WinFWUpg {8580CDDC-961B-4829-A80C-478D22DB7B3E} upgrade -F -asf asfv55
    old_image' will upgrade ASF for the adapter with the specified GUID.

        'WinFWUpg -all upgrade -ipmi pt5714h6.20 c:/backup/saveIPMI' will upgrade  
    for all the qualified BRCM 5714/15/80 adapters that currently support IPMI.  
    When multiple applicable adapters are present, the MAC address of the adapter 
    is appended to the backup NVRAM image parameter filename
    
        'WinFWUpg -all upgrade -F -ump c:/tmp/ump114 backupUMP' will force a 
    downgrade for all the BRCM 5714/15/80 adapters with existing UMP support.  
    When multiple applicable adapters are present, the MAC address of the adapter 
    is appended to the backup NVRAM image parameter filename.

        'WinFWupg -all restorenvram "c:/Documents and Settings/backup.bin" config' 
    reads a complete NVRAM image from file 'backup.bin' and write the image 
    to NVRAM along with its configurations.  If 'config' parameter is left out, 
    only the image is written. This will only restore NVRAM images to those with 
    matching FW, with the exception to variations in version numbers.

        'WinFwUpg prg -bc C:/tmp/fresh_bootcode' will program bootcode for the 
    ONLY qualified adapter found.  The adapter parameter can be omitted if ONLY ONE 
    qualified adapter is found.

        'WinFwUpg 0010181a1b1c cfg -mac 0010189d9e9f' will configure the selected 
    adapter whose current MAC address is 00:10:18:1a:1b:1c to be the new MAC address
    00:10:18:9d:9e:9f.

        'WinFwUpg 0010189a9b9c cfg -asf 1' will enable asf firmware if the asf 
    firmware is present in the selected adapter whose current MAC address is 
    00:10:18:9a:9b:9c.


6.2  Interactive Mode Examples:
*******************************

        'help' will display a list and descriptions of available commands.

        'q' will exit the utility.

        'dev' will display a list of upgradeable devices.

        'dev 0' will select device 0.

        'dir' will display a listing of the firmware programmed in NVRAM.

        'crc' will check the integrity of the NVRAM CRC.
 
        'dumpnvram c:\backup.bin config mac' will include all configurations
    including the MAC address and saves the dump file to the c drive.
    
        'restorenvram "c:\Document and Settings\backup.bin" config mac' 
    will include all configurations including the MAC address.  In order 
    to verify the MAC address was configured, exiting the program will be 
    necessary followed by either disabling and enabling the adapter or 
    rebooting the system.
    
        'upgrade -bc ee5755c3.19 backup5755.bin' will upgrade the boot code 
    for a BRCM 5755 adapter.

        'version' will display the version of Firmware Upgrade utility. 

        '-w 1' will enable the WOL setting on the current adapter.

        'prg -bc C:/tmp/new_bootcode" will program a blank NVRAM or overwrite
    NVRAM with the specified bootcode.

        'cfg -mac 0010181a2b3c" will configure MAC address for the selected
    qualified adapter.

        'cfg -ump 0' will disable ump firmware if the ump firmware is present
    in the selected adapter.


    Examples for Deprecated Commands:
    *********************************
    Note: These deprecated commands are kept to be backward compatible with
          earlier releases.

        'seprg -a a25755c7.09 backupASF.bin' will upgrade/program ASF on a
    5754/5755/5786/5787.  If no save_image parameter is specified, ASF 
    will be upgraded without a backup NVRAM image.

        'asfprg asfe5ini.bin asfe5cpa.bin asfe5cpb.bin' will upgrade asf on a 
    5705 adapter. If no parameters are specified after 'asfprg' it will 
    automatically search within the same location as winfwupg.exe for the files.

        'log log.txt' will create a text file 'log.txt' which will capture 
    all output and entered input.


7. Scope:
==============
Supported Operating Systems
    - Windows 98 SE 
    - Windows ME
    - Windows NT 4.0 SP6a
    - Windows 2000 SP4
    - Windows XP SP2 (IA-32, EM64T, AMD64)
    - Windows Server 2003 SP1 (IA-32, EM64T, AMD64)
    - Windows Server 2003 SNP
    - Windows Vista (IA-32, EM64T, AMD64)
    - Windows Preinstallation Environment (limited support).  
      For Windows PE, only the following commands are supported: 
      'prg', 'cfg', 'dir', 'dev', and 'crc'.


    ********************
    #      Notes:      #
    ********************

    - 'prg' command only supports 5754/5755/5787 Broadcom adapters.
       The image file for the 'prg' command is required to contain ONLY 
       valid bootcode without other firmware directories.

    -  Considerations for Windows Vista: 
       *********************************
       Administrative privileges are still required in order to run the 
       utility under Windows Vista.  However, when the user is other than 
       the local Administrator, the location for the backup file should 
       not be in a secure location as defined by the User Account Control 
       feature ( An example of a secured location includes, but is not 
       limited to, the root of the system drive).  Otherwise, the User 
       Account feature must be disabled in order for the utility to function 
       correctly and save the backup file to the desired secure location.


8. Disclaimer:
================ 

This version of the Windows Firmware Upgrade Utility has been validated only 
against the software component versions specified in the swdep.txt file.  
The Firmware Upgrade utility has not been qualified with other versions of 
the software components.  Using other software component version combinations 
has the potential to corrupt your NVRAM, resulting in an unusable network 
controller.  For this reason, Broadcom recommends that the software component 
versions listed in the swdep.txt file be used whenever possible.



