Broadcom Corporation Release Notes Broadcom NetXtreme Firmware Upgrade Tool for Linux Copyright (c) 2005-2010 Broadcom Corporation All rights reserved. Feb 02, 2010 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 | -mba | -asf | -ipmi | -ump | -mgmt | -wol | -aspm | -show} This command programs the specified configuration into NVRAM. -mac : is a 12-digit HEX MAC address, e.g. 0010181a2b3c. -mba : set to '1' to enable mba firmware. set to '0' to disable mba firmware. -asf : set to '1' to enable asf firmware. set to '0' to disable asf firmware. -ipmi : set to '1' to enable ipmi firmware. set to '0' to disable ipmi firmware. -ump : set to '1' to enable ump firmware. set to '0' to disable ump firmware. -mgmt : set to '1' to enable management firmware. set to '0' to disable management firmware. -wol : set to '1' to enable wol feature. set to '0' to disable wol feature. -aspm : set to '1' to enable L1 ASPM debounce feature. set to '0' to disable L1 ASPM debounce feature. -show : show the settings of current configuration. dev [] 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|-mba} {} [-c] [-p] This command programs NVRAM with the specified firmware image. -ib : iSCSI boot firmware -mba : MBA firmware : a mandatory parameter to specify the input binary file. -c : force to program iSCSI configuration, only valid when used with -ib option. -p : force to program iSCSI configuration utility program, only valid when used with -ib option. Note: 'prg' command only supports selective Broadcom adapters. dumpnvram {} Dumps the NVRAM contents to the specified file. is a mandatory parameter. Use forwardslash instead of backslash when specifying . Alternatively you could also use two backslashes in the file path. restorenvram {} [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. is the file name of NVRAM image. is a mandatory parameter. Use forwardslash instead of backslash when specifying . 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|-mgmt|-ib|-ib_ipv6|-ib_ipv4n6} [-c] [-p] {} [] This command upgrades the firmware or bootcode for the NetXtreme controller. The specifies the name of the file that contains the appropriate image. The specifies the name of the file to which the current NVRAM contents will be saved. If is not specified, the current NVRAM contents will not be saved. Both and 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) firmware -asf ASF firmware -ipmi IPMI firmware -ump UMP firmware -mgmt Management firmware -ib iSCSI boot firmware -ib_ipv6 iSCSI boot firmware to support IPv6 -ib_ipv4n6 iSCSI boot firmware to support IPv4 and IPv6 The [-c], [-p] option is valid only when "-ib" option is specified. -c upgrade the iSCSI configuration along with iSCSI boot code. The '-ib', '-ib_ipv6', and '-ib_ipv4n6' will add/upgrade the iSCSI configuration automatically. This option does not have effect any more. -p upgrade the iSCSI configuration program along with iSCSI boot code. reset reset the selected NIC. This command is only valid in Command Line Mode. -w {} The function enables or disables WOL setting. set to '1' to enable WOL. 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.