
                            Broadcom Corporation
              
                               Release Notes
                              
                  Broadcom NetXtreme Firmware Upgrade Tool
                                 for Linux
                         
                Copyright (c) 2005-2007 Broadcom Corporation
                            All rights reserved.
                              Oct 31, 2007


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

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

This utility is a console application which can be run from a Linux 
command prompt. The application will use the console to interact with 
the users.

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

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


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

     1.  Driver Versions: 
         tg3 Linux driver version 3.58b or above

         Please refer to README.TXT of the target driver for installation 
         instruction.

     2.  BMAPI version: 
         bmapilnx 6.3.41 or above.


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

     1.  To install lnxfwupg SDK package. 

         a.  Please do 'tar -zxvf lnxfwupg-{arch}.sdk.tgz' to untar the 
             package. 
 
             The files included in the sdk package are:
             1)  lnxfwupg                       -  This upgrade utility program
             2)  Readme.txt                     -  This file.
             3)  Release.txt

     2.  To install BMAPI library SDK package: 

         a. Do 'tar -zxvf bmapilnx-{version}.sdk.tgz' to untar the package
            in the same directory.

             The files included in the sdk package are:
             1)  bcmtype.h                     
             2)  BMAPI.h                   
             3)  brcm_pci.ids
             4)  BMAPILNX library
                 - For x86 platforms: 
                   libbmapi.so.{version}        BMAPI 32-bit shared library 

                 - For x86_64 platforms: 
                   libbmapi_x64.so.{version}    BMAPI 64-bit shared library 
                   libbmapi.so.{version}        BMAPI 32-bit shared library 

                 - For PPC64 platforms: 
                   libbmapi_ppc64.so.{version}  BMAPI 64-bit shared library for PPC

           
4. Command Usage:
=================
  
Usage:
  lnxfwupg [ -all | [ID | MAC] ] [Commands]
    The '-all' option applies to 'upgrade' and 'restorenvram' commands
    only. 

    The ID/MAC is optional for 'help', 'version', and 'dev'
    commands, but it is required for all other commands.

    1. When '-all' is specified, 'ID' 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 information. 

    2. On Linux, 'ID' is the the interface name (i.e. ethX). 

    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 'ifconfig' 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
    prg         : Program NVRAM with specified firmware image
    dumpnvram   : save entire NVRAM content to a file
    restorenvram: restore entire NVRAM content from a file
    version     : display version of this program
    upgrade     : upgrades the firmware or bootcode
    -w          : Enable/Disable WOL


    cfg {-mac <MAC address to be programmed for current selected device> | 
         -mba <value> | -asf <value> | -ipmi <value> | -ump <value> |
         -wol <value> | -aspm <value> | -show}
        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.
        -wol        : set <value> to '1' to enable wol feature.
                      set <value> to '0' to disable wol feature.
        -aspm       : set <value> to '1' to enable L1 ASPM debounce feature.
                      set <value> to '0' to disable L1 ASPM debounce feature.
        -show       : show the settings of current configuration.

    dev [<number>]
        <number> is the adapter to be selected as target device

    dir
        Displays a listing of the firmware programmed in NVRAM.

    crc 
        Checks the integrity of the NVRAM CRC,

    prg {-ib} {<new_image>} [-c] [-p]
        This command programs NVRAM with the specified firmware image.
        -ib        : iSCSI boot firmware
        <new_image>: a mandatory parameter to specify the input binary file.
        -c         : force to program iSCSI configuration.
        -p         : force to program iSCSI configuration utility program.
        Note: 'prg' command only supports selective Broadcom adapters.
              The image file for the 'prg' command is required to contain ONLY 
              valid iSCSI boot without other firmware directories.

    dumpnvram {<filename>}
        Dumps the NVRAM contents to the specified file.
        <filename> is a mandatory parameter. Use forwardslash instead of 
        backslash when specifying <filename>. Alternatively you could also 
        use two backslashes in the file path.

    restorenvram {<filename>} [idmatch] [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. Use forwardslash instead of 
        backslash when specifying <filename>. Alternatively you could also 
        use two backslashes in the file path.
        'idmatch' requests the Firmware Upgrade Tool to restore the NVRAM
        image only after the 4 IDs (vendor_id, device_id, subsystem_vendor_id,
        subsystem_device_id) in the image file match those in the device.
        This is on top of all previous criteria that have to be met.
        '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.

    version
        displays version of this program.

    upgrade [-noreset] [-F] {-bc|-mba|-asf|-ipmi|-ump|-ib} {<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.
        Use forwardslash instead of backslash when specifying file path.
        Alternatively you could also use two backslashes in the file path.
        If the upgrade version is same or older than the version
        in NVRAM, upgrade will be aborted.
        The -noreset option is to skip the driver restart of the selected
        NIC after the firmware upgrade is completed.  This option is only
        valid in Command Line Mode.
        The -F option is to force the upgrade without checking version.
            OPTION           NAME OF FIRMWARE OR BOOT IMAGE
            -bc                bootcode
            -mba               MBA (PXE) code
            -asf               upgrade ASF
            -ipmi              IPMI code
            -ump               UMP firmware
            -ib                iSCSI boot firmware

    reset
        reset the selected NIC.  This command is only valid in Command Line Mode.

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


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
#define FWUPG_SYSTEM_REBOOT                     95  // System Reboot required


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:
*******************************

        'lnxfwupg' will enter interactive mode.

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

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

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

        'lnxfwupg -all upgrade -ipmi pt5714h6.20 /tmp/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
    
        'lnxfwupg -all upgrade -F -ump /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.

        'lnxfwupg -all restorenvram /tmp/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.

        'lnxfwupg 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.

        'lnxfwupg 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 /tmp/backup.bin config mac' will include all configurations
    including the MAC address and saves the dump file to the c drive.
    
        'restorenvram /tmp/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.

        '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 lnxfwupg for the files.

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



7. Known Limitations:
=====================

  1.  The read/write NVRAM operations for this utility are done through 
      the APIs provided by BMAPILNX. Consequently, its ability to support 
      Redhat EL3.0 is impacted by the "Known Limitations" as documented 
      in BMAPILNX readme.txt (see the following extracted note). In summary, 
      all commands requiring NVRAM access are unable to perform correctly on 
      Red Hat EL3.0 with kernel versions prior to 2.4.23.

      "Known Limitations" extracted from BMAPILNX readme.txt:

        Due to a limitation in kernel versions prior to 2.4.23, older
        Linux distributions including Red Hat EL 3.0 may cause BMAPI
        not function with error code 58 to indicate BMAPI_EEPROM_CORRUPTED.
        This problem is seen on 32-bit and 64-bit platforms with 57xx 
        family NICs loaded with tg3 driver (version >= 3.37) and 5706 
        family NICs loaded with bnx2 driver.
  
  2.  The current version of this tool has been tested on Red Hat 4, SuSE 9, 
      SuSE 10, Mandriva 2006, and Turbo 11 for i386, x86_64, and PowerPC CPU 
      architectures using 2.6.x kernels. 

  3.  The '-all' option is available in releases >= v1.0.3.



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

This version of the Linux 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.

