Copyright 2004-2019 Broadcom. All Rights Reserved.
The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
                        
                           ELXFLASHOFFLINE
                Firmware Update Utility Release Notes
                              9 July 2020


Contents:

    elxflash version 12.6.221.31

Dependencies:

    LinLpCfg version 12.6.221.31
    

The top level directory of the kit provides the executables, config
files and scripts for running the elxflash tool.
This installation kit contains the following components:

elxflash     - the executable to perform firmware downloads
flash        - the executable to perform NCSI downloads on supported UCNAs
fwmatrix.txt - example fwmatrix file
lcreflsh.sh  - script for invoking unattended update
readme.txt   - readme file for this kit
boot         - directory for boot code image files for Emulex HBAs
firmware     - directory for firmware image files for Emulex HBAs

The boot and firmware directories are used by elxflash when updating an HBA.
The developer must populate the boot and firmware directories with the 
appropriate file images to perform the desired download operation.


-------------------------------------------------------------------------------


Usage:

elxflash      [/auto] [/downgrade] [/e] [/f] [/fb] [/fc] [/ff]
              [/fmd=<fwmatrix_dir>] [/g] [/help] [/id=<image_dir>]
              [/iv=<image_file>] [/log=<logfile>] [/p] [/q] [/rewrite] [/s]
              [/sysfs] [/ucna] [/update] [/v] [/vpd] [/?]
              
  /auto       Auto - Instructs Elxflash to ignore the fwmatrix.txt file,
              automatically discover HBAs, and to perform specified
              operations (/fb, /ff, /downgrade, /rewrite, or /update) 
              using the firmware and boot directories.
              This switch requires the use of Emulex defined firmware and 
              boot code file names in their respective directories.
              See AUTO DISCOVERY FAQs for a more detailed explanation.
              
  /downgrade  Downgrade - For each installed and supported HBA, the current 
              firmware and boot code versions are compared with versions in
              fwmatrix.txt. If the downgrade versions in fwmatrix.txt are 
              lower than the currently installed versions then the downgrade 
              versions of firmware and/or boot code are downloaded to 
              that HBA.
              
              When this switch is used with /auto, the fwmatrix.txt 
              configuration file is ignored. The user must place the desired 
              downgrade versions of firmware and boot code in their 
              respective directories. The downgrade versions are compared 
              to the installed versions. If the downgrade versions are lower 
              than the installed versions then the downgrade versions are 
              downloaded to the HBA. If multiple versions of firmware and 
              boot code are found, the next-previous downgrade versions 
              of firmware and boot code will be downloaded to the HBA.
              See AUTO DISCOVERY FAQs for a more detailed explanation.
              
  /e          Rewrite - Equivalent to using /rewrite.
              
  /f          Force Fw and Boot - Equivalent to using /fb and /ff.
              
  /fb         Force Boot Code - For each installed and supported HBA, force a 
              download of the boot code specified in the fwmatrix.txt file.
              
              When this switch is used with /auto, the fwmatrix.txt 
              configuration file is ignored. The user must place the desired 
              boot code in the boot directory. If multiple versions of boot 
              code are found for an HBA, the highest available version of boot 
              code will be downloaded to the HBA.
              See AUTO DISCOVERY FAQs for a more detailed explanation.
			  
  /fc         FC Only - Process FC HBA's only.
              
  /ff         Force Firmware - For each installed and supported HBA, force a
              download of the firmware specified in the fwmatrix.txt file.              
              
              When this switch is used with /auto, the fwmatrix.txt 
              configuration file is ignored. The user must place the desired 
              firmware in the firmware directory. If multiple versions of 
              firmware are found for an HBA, the highest available version of 
              firmware will be downloaded to the HBA. 
              See AUTO DISCOVERY FAQs for a more detailed explanation.
              
  /fmd=<fwmatrix_dir> Base directory where the fwmatrix.txt file is located.
              
  /g          Downgrade - Equivalent to using /downgrade.
              
  /help or /? Display this help message.
              
  /log=<logfile> Append the output of this utility to the specified text file.
              
  /id=<image_dir> Base directory where the firmware and boot directories
              are located.
              
  /iv=<image_file> Display the image file's version.
              
  /p          Preview Download - For each installed and supported HBA,
              perform a download preview using the firmware and boot code
              specified in the fwmatrix.txt file.
              
  /q          Query - Display the HBA model, WWN, PCI ID, firmware and boot 
              code versions for each installed HBA.
              
              When this switch is used with a download switch, an additional 
              field called "Supported Firmware" or "Supported Boot Code" 
              will be displayed. This field signifies the firmware or boot code
              image that Elxflash will attempt to download.
              
  /rewrite    Rewrite - For each installed and supported HBA, the current 
              firmware and boot code versions are compared with versions in
              fwmatrix.txt. If the currently installed versions are less than 
              or equal to the rewrite versions in fwmatrix.txt then the rewrite
              versions of firmware and/or boot code are downloaded to the HBA.
              
              When this switch is used with /auto, the fwmatrix.txt 
              configuration file is ignored. The user must place the desired 
              rewrite versions of firmware and boot code in their 
              respective directories. The rewrite versions are then compared 
              to the installed versions. If the installed versions 
              are less than or equal to the rewrite versions then the rewrite 
              versions are downloaded to the HBA. If multiple rewrite versions 
              of firmware or boot code are found, the highest available 
              versions will be downloaded to the HBA.
               
              See AUTO DISCOVERY FAQs for a more detailed explanation.
              
  /s          Silent - Mute all output to stdout.
              
  /sysfs      SysFS UCNA Discovery - Elxflash will discover UCNA functions
              via SysFS. This feature requires libsysfs.
              
  /ucna       UCNA Only - Process UCNA's only.
              
  /update     Update - For each installed and supported HBA, the current 
              firmware and boot code versions are compared with versions in
              fwmatrix.txt. If the update versions in fwmatrix.txt are higher
              than the currently installed versions then the update versions 
              of firmware and/or boot code are downloaded to that HBA.
              
              When this switch is used with /auto, the fwmatrix.txt 
              configuration file is ignored. The user must place the desired 
              update versions of firmware and boot code in their 
              respective directories. The update versions are then compared 
              to the installed versions. If the update versions 
              are higher than the installed versions then the update versions 
              are downloaded to the HBA. If multiple update versions of 
              firmware or boot code are found, the highest available versions 
              will be downloaded to the HBA.
              See AUTO DISCOVERY FAQs for a more detailed explanation. 
              
  /v          Verbose - Display progress messages. When this switch is used,
              a summary message will appear detailing all of the download 
              operations that were performed.
              
  /vpd        VPD Model Name - Display VPD model name for each supported
              HBA. This switch must be used with additional operational
              switches.

-------------------------------------------------------------------------------


AUTO DISCOVERY FAQs

The "/auto" switch instructs Elxflash to ignore the fwmatrix.txt file, 
automatically discover HBAs, and to perform specified operations
(/ff, /fb, /downgrade, /rewrite, or /update) using the boot and firmware 
directories. This switch requires the use of Emulex defined firmware and 
boot code file names in their respective directories.

Note concerning Boot Code downloads:

When multiple compatible versions of boot code are found during a boot code
download, Elxflash will first try to auto discover the best image match by
adapter family and boot type. If a match is not found, Elxflash will try to
find a match by adapter family.


Example usage with auto discovery:

elxflash /auto /ff
The firmware directory will be used to find a compatible firmware file for an
HBA. If there are multiple versions of firmware for an HBA, the highest version
will be used for the "force firmware" operation.


elxflash /auto /fb
The boot directory will be used to find a compatible boot code file for an
HBA. If there are multiple versions of boot code for an HBA, the highest 
version will be used for the "force boot code" operation.


elxflash /auto /update
The firmware and boot directories will be used to find compatible versions of 
firmware and boot code. If there are multiple versions of compatible firmware 
and/or boot code, the highest versions will be used for the "update" operation.
Since multiple compatible versions of boot code may exist, the highest boot
code version is chosen in the following order:
Universal (U), Pair (P), Open (O), EFI (E) and x86 (B).

The highest boot code version is downloaded regardless of the installed 
boot code. This allows upgrading from one type of boot code to another type.


elxflash /auto /downgrade
The firmware and boot directories will be used to find compatible versions of 
firmware and boot code. If there are multiple versions of compatible firmware 
and/or boot code, the next-previous versions will be used for the "downgrade" 
operation.
As an example, if the current firmware on an HBA is ZF280A3.ALL and
firmwares ZF280A2.ALL, and ZF280A1.ALL are detected in the firmware directory,
the "downgrade" operation will downgrade the current firmware to ZF280A2.ALL. 
This algorithm is also applied to downgrading the boot code.


elxflash /auto /update /preview
The firmware and boot directories will be used to perform a preview download. 
Elxflash will search the firmware and boot directories for compatible versions 
and if there are multiple versions of compatible firmware and/or boot code, 
the highest versions will be used for the update operation.


elxflash /auto /rewrite
The firmware and boot directories will be used to find compatible versions of 
firmware and boot code. If there are multiple versions of compatible firmware 
and/or boot code, the highest versions will be used for the "rewrite" operation.


-------------------------------------------------------------------------------


Return codes:

0:  Good  - All upgrades completed successfully.
1:  Good  - No HBA's needed to be updated.
2:  Error - All HBA's that could be upgraded failed to be upgraded.
3:  Error - Some HBA's that could be upgraded failed to be upgraded.
4:  Error - Emulex command line application kit error.
5:  Error - No supported HBA's found.
6:  Error - When using auto discovery, the firmware and/or boot directory 
            were not found.
7:  Good  - When using auto discovery, no suitable updates were found.


Detailed error messages returning code 0:

  elxflash: All required boot code downloads succeeded - Return Code=0
  elxflash: All required downgrades succeeded - Return Code=0
  elxflash: All required firmware downloads succeeded - Return Code=0
  elxflash: All required firmware and/or boot code downloads 
            succeeded - Return Code=0
  elxflash: All required rewrites succeeded - Return Code=0
  elxflash: All required updates succeeded - Return Code=0


Detailed error messages returning code 1:

  elxflash: No boot code downloads required - Return Code=1
  elxflash: No downgrades required - Return Code=1
  elxflash: No firmware downloads required - Return Code=1
  elxflash: No firmware and/or boot code downloads required - Return Code=1
  elxflash: No rewrites required - Return Code=1
  elxflash: No updates required - Return Code=1


Detailed error messages returning code 2:

  elxflash: Error - all required boot code downloads failed - Return Code=2
  elxflash: Error - all required downgrades failed - Return Code=2
  elxflash: Error - all required firmware downloads failed - Return Code=2
  elxflash: Error - all required firmware and/or boot code downloads
                    failed - Return Code=2
  elxflash: Error - all required rewrites failed - Return Code=2
  elxflash: Error - all required updates failed - Return Code=2 
  elxflash: Error - fwmatrix update table not found - Return Code=2
  elxflash: Error - insufficient privileges - Return Code=2
  elxflash: Error - invalid switch options - Return Code=2


Detailed error messages returning code 3:

  elxflash: Error - some required boot code downloads failed - Return Code=3
  elxflash: Error - some required downgrades failed - Return Code=3
  elxflash: Error - some required firmware downloads failed - Return Code=3
  elxflash: Error - some required firmware and/or boot code downloads
                    failed - Return Code=3
  elxflash: Error - some required rewrites failed - Return Code=3
  elxflash: Error - some required updates failed - Return Code=3


Detailed error messages returning code 4:

  elxflash: Error - Emulex command line application kit not 
            installed - Return Code=4
  elxflash: Error - elxhbamgr is not running - Return Code=4
  elxflash: Error - LPFC driver not loaded - Return Code=4
  elxflash: Error - unable to process command - Return Code=4
  elxflash: Error - unable to open logfile - Return Code=4


Detailed error messages returning code 5:

  elxflash: Error - no supported Emulex HBAs found - Return Code=5


Detailed error messages returning code 6:

  elxflash: Error - the boot subdirectory was not found - Return Code=6
  elxflash: Error - the firmware subdirectory was not found - Return Code=6


Detailed error messages returning code 7:

  elxflash: No compatible boot code found - Return Code=7
  elxflash: No compatible firmware found - Return Code=7
  elxflash: No compatible firmware or boot code found - Return Code=7


<EOF>
