Intel(R) Ethernet Flash Firmware Utility
========================================
September 21, 2018

CONTENTS
========
- OVERVIEW
- RUNNING THE UTILITY
- COMMAND LINE OPTIONS
- EXAMPLES
- EXIT CODES
- INSTALLATION
- CUSTOMER SUPPORT
- LEGAL


Overview
========
The Intel(R) Ethernet Flash Firmware Utility (BootUtil) is used to update
configurations and program the PCI option ROM on the flash memory of supported
Intel PCI and PCI-Express-based network adapters.
BootUtil replaces existing utilities and provides the functionality of the
older IBAUTIL, ISCSIUTL, LANUTIL, and FLAUTIL. BootUtil supports all the
adapters supported by the previous utilities.

NOTE: Updating the adapter's flash memory using BootUtil will erase any
existing firmware image from the flash memory.

Intel provides the following flash firmware in FLB file format for programming
to the flash memory:

- Intel(R) Boot Agent as PXE Option ROM for legacy BIOS
  http://www.intel.com/support/network/adapter/pro100/bootagent/
- Intel(R) iSCSI Remote Boot as iSCSI Option ROM for legacy BIOS
  http://www.intel.com/support/network/iscsi/remoteboot/
- Network Connectivity, UEFI network driver
  http://www.intel.com/support/network/sb/cs-006120.htm

OEMs may provide custom flash firmware images for OEM network adapters. Please
refer to the instructions given by OEMs.

BootUtil allows the user to flash supported firmware to the adapter from the
included master FLB file. This option ROM includes PXE, UEFI, iSCSI, and FCoE
drivers, and the image is programmed to the flash memory at once. BootUtil will
also build the required combo images for supported adapter and program those
images to the flash, as well. Since both discrete and combo images are
supported, the -BOOTENABLE command ONLY works on combo images.

PXE+EFI and iSCSI+EFI image combinations are supported for all OEM generic
adapters, however support is limited to devices which support both technologies
as discrete images. However, flash size is a limiting factor, as the image size
can change without notice.

The Master FLB file (BOOTIMG.FLB) is the new container for all the Intel(R)
boot Option ROMs. This file replaces the existing FLB files for PXE, EFI,
iSCSI, and FCoE.

BootUtil without command-line options will display a list of all supported
Intel network ports in the system. BootUtil will also allow the user to enable
or disable the flash memory on specific ports by using -FLASHENABLE or
-FLASHDISABLE options in order to control access to the firmware from the
system.

BootUtil allows the user to individually set iSCSI, FCoE, UEFI and PXE boot
configurations by -NIC=xx -<OPTION>=<VALUE> options. The -I option is iSCSI
specific and will not work for PXE configurations.

NOTES:
  * BootUtil displays up to 128 adapter ports.
  * No configuration settings are supported for the UEFI driver.
  * -NIC, -MACADDR, and -DEVID are mutually exclusive. You cannot use more than
    one of these options per command. Specifying more than one option will
    cause BootUtil to fail.

Check the Intel Customer Support (http://support.intel.com) website for the
latest information and component updates.


RUNNING THE UTILITY
===================
Using the "/?" option will display a list of supported command line options.
The syntax for issuing BootUtil command-line options is:
BOOTUTIL -[OPTION] or -<OPTION>=<VALUE>


COMMAND LINE OPTIONS
====================
BootUtil accepts one executable option and its associated non-executable
options in an execution. If conflicting executable options are specified,
BootUtil exits with an error.

The options, where applicable, are listed in logical groups.

NOTE: If you run BootUtil without any command-line options, the utility
displays a list of all supported Intel network ports found in the system.

GENERAL OPTIONS:
-? or -HELP
  Displays a list of command-line options.
-ALL
Selects all supported network ports found in the system.
-64d
  Disables 64-bit BAR (Base Address Register) addressing on the selected port.
  This restricts the system BIOS to assigning 32-bit BARs to the port.
-64e
  Enables 64-bit BAR addressing on the selected port.
-BLINK
  Blinks the LED on the selected port for ten seconds.
-DEVID=[Device ID]
  Selects the network port specified by [Device ID]. [Device ID] is a 4 digit
  hexadecimal number, prepended by 0x.
-EXITCODES
  Displays exit codes returned to the OS environment by BootUtil.
-E
  Enumerates all supported network ports in the system.
-FILE=[FILENAME]
  Specifies the file name for -SAVEIMAGE, -RESTOREIMAGE, -SAVECONFIG,
-RESTORECONFIG, -UP or -UPDATE options.
-I=[FILENAME]
  Reads iSCSI boot configuration options from [FILENAME] script file and program
  settings on the selected port.
-IMAGEVERSION or -IV
  Displays firmware types and version numbers from a resource image. If used
  with the -FILE option, the resource image is in the FLB file. If used with
  the -NIC option, the resource image is in the adapter flash. If used with
  the -ALL option, each resource image is continuously displayed for all
  adapters.
-MACADDR=[MAC address string]
  Selects the network port specified by [MAC address string]. [MAC address
  string] is a 12 digit number. Separators (":" or "-") are allowed but not
  required.
-NIC=XX
  Selects a specific network port in the system. If used without any executable
  option, it prints the iSCSI boot configuration of the selected port, or saves
  it in the file when the -O option is used.
-NODPL
  With command, BootUtil does not display the PCI device location.
-O=[FILENAME]
  Must be used with -E or -NIC. If used with the -E option, saves a list of all
  NICs and their MAC addresses to the specified file. If used with the -NIC
  option, saves all iSCSI Remote Boot configuration options for the specified
  NIC to the specified file.
-P
  With this command, BootUtil pauses screen after displaying every 25th line.
  In pause mode, last line of the screen will contain information that:
    - screen has been paused, and
    - user can press Enter to continue
-TARGET=XX
  This is an FCoE-specific selection option. Legal values are 1,2,3,and 4.
  This option is required for configuration commands -WWPN, -FCOELUN, FCOEVLAN,
  and -BOOTORDER.

POWER MANAGEMENT OPTIONS:
-WOLENABLE or -WOLE
  Enables Wake On LAN (WOL) functionality on the selected port.
-WOLDISABLE or -WOLD
  Disables Wake On LAN (WOL) functionality on the selected port.

ADAPTER FLASH ENABLE/DISABLE OPTIONS:
-BOOTENABLE=[PXE, ISCSIPRIMARY, ISCSISECONDARY, FCOE, or DISABLED]
  Selects flash firmware type to enable or disable on the selected port. The
  combo option ROM could have all capabilities. The monolithic option ROM has
  either PXE, iSCSI, or FCoE capability but not all. This command will NOT WORK
  on monolithic Option ROMs.

NOTE: This manual command is not applicable to the UEFI network driver. The UEFI
    network driver is enabled by default and loaded automatically unless network
    ports are already used by other flash firmware.

    BOOTENABLE=DISABLED
    Disables iSCSI, PXE and FCoE functionalities for legacy BIOS.

    BOOTENABLE=FCOE
    Enables FCoE and disables iSCSI/PXE boot for legacy BIOS.

    BOOTENABLE=ISCSIPRIMARY
    Enables port as iSCSI primary and disables PXE/FCoE for legacy BIOS.

    BOOTENABLE=ISCSISECONDARY
    Enables port as iSCSI secondary and disables PXE/FCoE for legacy BIOS.

    BOOTENABLE=PXE
    Enables PXE and disables iSCSI/FCoE boot for legacy BIOS.

-FLASHENABLE or -FE
  Enables the capability to run flash firmware on the selected adapter.

NOTE: This parameter is not supported on the following adapters:
  - Intel(R) Gigabit ET Quad Port Mezzanine Card
  - Intel(R) Ethernet X520 10GbE Dual Port KX4 Mezz
  - Intel(R) Ethernet X520 10GbE Dual Port KX4-KR Mezz

-FLASHDISABLE or -FD
  Disables the capability to run flash firmware on the selected adapter.
  NOTE: This parameter is not supported on the following adapters:
    - Intel(R) Gigabit ET Quad Port Mezzanine Card
    - Intel(R) Ethernet X520 10GbE Dual Port KX4 Mezz
    - Intel(R) Ethernet X520 10GbE Dual Port KX4-KR Mezz

FLASH PROGRAMMING OPTIONS:
-QUIET
  Runs BootUtil without confirmation prompts. This option is used with
   -IMAGEVERSION, -UP, -UPDATE, -RESTOREIMAGE, or -HELP option.
-RESTOREIMAGE or RI
  Restores a previously-saved firmware image to the same network adapter using
  the -NIC option. The source file is specified by the -FILE option.
-SAVEIMAGE or SI
  Saves the existing firmware image in the flash memory of the adapter
  specified by the -NIC option to a disk file. The destination file is
  specified by the -FILE option.
-UP or -UPDATE=[ROMType] [-FILE=Filename]
  Updates the flash memory of the adapter specified by the -NIC option with the
  given FLB flash firmware image file. If -QUIET is not specified, the user is
  prompted to confirm overwriting the existing firmware image before upgrading.
  If a Filename is not provided, the utility looks for the default <bootimg.FLB>
  file which contains all image types.

The following examples use PXE, but could also be efi, efi64, FCoE or iSCSI.
  Bootutil -Nic=x -up=pxe
  Bootutil -Nic=x -up=pxe -file=pxeimg.flb

If your adapter supports a combo option rom, the following command option
automatically detects the supported combo image and programs the adapter with
that image.
  -up=combo
    up=pxe+efi and up=iscsi+efi are valid.

PXE BOOT CONFIGURATION OPTIONS: (Can be used with -NIC or -ALL)
-DEFAULTCONFIG or -DEFCFG
  Sets the PXE configuration of the selected NIC back to default settings.
-MODE
  This parameter should not be used except as advised by Intel Support
  personnel.
-TITLEENABLE OR -TLE
  Enables Initial Title Message.
-TITLEDISABLE OR -TLD
  Disables Initial Title Message.

ISCSI BOOT CONFIGURATION OPTIONS:
-RESTORECONFIG
  Restores previously-saved iSCSI boot configuration snapshot on the selected
  port. Need the -FILE option to specify the saved data. WARNING: This feature
  may create multiple primary or secondary ports if the same command is issued
  to multiple ports. Review the boot priority setting in the iSCSI setup menu
  for the next system boot.
-SAVECONFIG
  Saves a snapshot of iSCSI boot configurations on the selected port to a binary
  file. Need to specify the file name by the -FILE option. WARNING: For security
  reasons it is recommended that CHAP settings are disabled when using this
  option.

PORT CONFIGURATION OPTIONS FOR ISCSI INITIATOR:
These options can either be used individually with the -NIC=XX option, or in a
script file with the -I option. The value is specified in -<OPTION>=<VALUE>
format.

-BOOTPRIORITY
  Specifies iSCSI boot priority as PRIMARY, SECONDARY or DISABLE.
-GATEWAY
  Specifies the gateway IPv4 address in dotted decimal notation.
-INITIATORDHCP
  Enable or disable to get initiator configuration from DHCP.
-INITIATORIP
  Specifies the initiator IPv4 address in dotted decimal notation.
-INITIATORNAME
  Specifies the iSCSI Qualified Name (IQN) for the initiator.
-NETMASK
  Specifies the initiator subnet mask in dotted decimal notation.

ISCSI TARGET CONFIGURATION OPTIONS:
These options can either be used individually with the -NIC=XX option, or in a
script file with the -I option. The value is specified in -<OPTION>=<VALUE>
format.
-BOOTLUN
  Specifies the LUN number to boot from.
-TARGETDHCP
  Enable or Disable to get the target information from DHCP Root Path.
-TARGETIP
  Specifies the target IPv4 address in dotted decimal notation.
-TARGETNAME
  Specifies the iSCSI Qualified Name (IQN) for the target.
-TARGETPORT
  Specifies the TCP port number on the target to connect to.

AUTHENTICATION CONFIGURATION OPTIONS:
These options can either be used individually with the -NIC=XX option, or in a
script file with the -I option. The value is specified in -<OPTION>=<VALUE>
format.
-AUTHENTICATIONMETHOD
  Specifies either NONE, CHAP or MUTUALCHAP.
-CHAPUSERNAME
  Specifies CHAP user name
-CHAPSECRET
  Specifies a secret text string to go with the CHAP user name.
  (secret must be 12 to 16 characters long)
-MUTUALCHAPSECRET
  Specifies the reverse (target) CHAP secret text string.
  (secret must be 12 to 16 characters long)

FCOE GENERAL CONFIGURATION OPTIONS:
These options have to be used with the -NIC=XX option. They cannot be used with
the -ALL option.
-WWNNPREFIX
  Specifies the Prefix to use for the WWNN. The prefix comprises of 4 hex
  digits. Separators '-' or ':' are allowed but optional. For example:
    BOOTUTIL -NIC=1 -WWNNPREFIX=1000-00
-WWPNPREFIX
  Specifies the Prefix to use for the WWPN. The prefix comprises of 4 hex
  digits. Separators '-' or ':' are allowed but optional. For example:
    BOOTUTIL -NIC=1 -WWPNPREFIX=20-00

FCOE TARGET CONFIGURATION OPTIONS:
These Options require the use of both the -NIC=XX Option AND the -TARGET=XX
Option. The -ALL option is not allowed.
-BOOTORDER
  Specifies the boot order for the selected target. Valid range is 1-4. Boot
  order values of 1-4 can only be assigned once to target(s) across all FCoE
  boot-enabled ports. If 0 is specified then this target will be excluded from
  the boot order.
  NOTE: These commands can all be used on the same command-line to configure
  an entire target in one shot. For example:
    BOOTUTIL -NIC=1 -TARGET=2 -WWPN=0011223344556677 -FCOELUN=0
      -FCOEVLAN=1 -BOOTORDER=2
-FCOELUN
  Specifies the LUN for the selected FCoE Target. Valid range is 0..255.
-FCOEVLAN
  Specifies the VLAN to use in order to connect to the selected target.
  Valid range is 0..4094.
-WWPN
  Specifies the WWPN for the selected Target. The WWPN consists of 16 HEX
  digits or 8 bytes. Each byte can be separated with '-' or ':' as an optional
  separator. For example:
    BOOTUTIL -NIC=1 -TARGET=1 -WWPN=00-11-22-33-44-55-66-77

The CHAP Authentication feature of this product requires the following
acknowledgements: This product includes cryptographic software written by Eric
Young (eay@cryptsoft.com). This product includes software written by Tim Hudson
(tjh@cryptsoft.com) This product includes software developed by the OpenSSL
Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)


EXAMPLES
========
The following examples show how to enter some typical BootUtil command lines:

Example: To enable the flash firmware on the first network adapter for the
system to be capable of executing the flash firmware.
  BootUtil -NIC=1 -FLASHENABLE

Example: To disable the flash firmware on all the network adapters.
  BootUtil -ALL -FD

Example: To display BootUtil FLB flash firmware types and versions.
  BootUtil -IMAGEVERSION

Example: To update all ports of a supported NIC with PXE.
  1. BootUtil -UP=PXE -ALL (Assumes input file is bootimg.flb)
  2. BootUtil -UP=PXE -ALL -FILE=BOOTIMG.FLB (explicit user specified file)

Example: To update a combo image on supported adapter (eg, pxe+iscsi)
  1. BootUtil -UP=Combo -NIC=2 -FILE=BOOTIMG.FLB

The above command will succeed if the PXE+ISCSI combination is supported on
NIC #2. If not an error is displayed to the user.

NOTE: THE -UP and -UPDATE commands are equivalent and interchangeable.

Example: To enable PXE firmware on the third network port in the system.
  BootUtil -BOOTENABLE=PXE -NIC=3

NOTE: This command will work only if PXE is part of a combo Option ROM and
not a discrete Option ROM.

Example: To disable the firmware on the second network port in the system.
  BootUtil -NIC=2 -BOOTENABLE=DISABLED

Example: To get help descriptions.
  BootUtil -?

Example: To enable DHCP for the iSCSI initiator on all the network ports in the
system.
  BootUtil -INITIATORDHCP=ENABLE -ALL

Example: To load the iSCSI boot configurations from a text script file to the
first network port.
  BootUtil -I=CONFIG.TXT -NIC=1


EXIT CODES
==========
BootUtil returns an exit code to the OS environment. Possible exit codes are
listed below:
Code Name                                      Value
----------------------------------------------+-----
All BootUtil operations completed successfully   0
Bad command-line parameter                       1
No supported network port detected               2
Invalid network port selected                    3
FLASH operation failed                           4
EEPROM read operation failed                     5
EEPROM write operation failed                    6
File content is missing or corrupt               7
Operator termination                             8
LOM not supported for selected operation         9
Network port is not bootable                    10
FLASH memory is disabled for flash firmware     11
FLASH memory too small for selected firmware    12
Programming iSCSI boot configurations failed    13
System memory allocation failed                 14
File operation failed                           15
FCoE operation failed                           16


Installation
=============


INSTALLING THE TOOL ON MICROSOFT* WINDOWS*
===========================================

To install the tools' drivers on Windows, run install.bat from the appropriate
directory of the install package.

Although the tool are not installed with install.bat, the driver that the tool
requires is copied into the local machine Windows driver directory. To run the
tool, launch a Command Prompt window from the Windows Start Menu. Go to the
media and directory where the tool is located and run the utility. The readme
files for each tool are found in the same directory as the tool. These tools
can be manually installed on the local hard drive in any directory.

The tool uses its own driver file (not the same as the system network driver).
If the driver sys file already exists in the drivers directory, install.bat may
fail to copy. Using the /y switch with install.bat will override and copy the
driver file regardless. However, this can be dangerous if an older version of
the driver is being used by another application such as Intel(R) PROSet for
Windows Device Manager. If a driver is already present in the drivers
directory, try running the tool from the command prompt. If it runs, then the
driver is fine. The tool will not run if the driver version present does not
match the driver version expected.

Note that you must have access to the %systemroot%\system32\drivers directory.
Only the administrator account has these privileges. You must be logged in as
administrator or the tools must be run as administrator.

Note that on Windows, any device that is disabled in device manager will not be
accessible by tools due to no memory resources. You would get an error code
0xC86A800E. To solve this problem, you can do one of the following:
1) Re-enable the device in device manager. Never disable this device when
   using tools.
2) Install an NDIS device driver for the device and make sure that it does
   not have a yellow or red bang by it in device manager.
3) Delete the device from device manager and restart the system. The install
   new hardware wizard should appear on next reboot. Do not cancel this. Just
   move the window aside and run the tool(s). Generally, you can click "cancel"
   on the wizard but there are some cases where Windows will disable the memory
   resources causing you to get back into the same state.


INSTALLING THE TOOLS ON EFI
===========================

The EFI 1.x tools are not supported in this release.

There is no installation required for EFI tools. The tools can simply be copied
from the appropriate directory to the drive that they will run from. The EFI2
binaries are for use with the UEFI Shell 2.X with the UEFI 2.3 HII protocol.
EFI2 tools will not run on the EFI Shell 1.X or if the UEFI 2.3 HII protocol is
not present.

Note that while EFI supports USB drives, there may be issues running tools from
the USB drive. Whether or not there are issues are BIOS specific. If you
experience issues, run the tool from hard disk instead.


INSTALLING THE TOOLS ON DOS
===========================

The tools support various DOS versions. There is no installation required for
DOS tools. The tools can simply be copied from the DOS directory on the CD to
the drive that they will run from. It is expected that the tools have a clean
boot environment. The tools will not run with memory managers and/or DOS
networking drivers loaded. The tools expect that they have full, unlimited
control of the hardware. The tools *WILL NOT* run properly if EMM386 is
present. The tools run in protected mode, 32-bit DOS. Therefore, they will not
be compatible with any TSR programs.


INSTALLING THE TOOLS ON LINUX*
==============================

In order to run tools on Linux*, a driver stub must be built and installed on
the system. This driver is not related to the network device driver that is
used to run the network during live traffic. It is a separate driver used
explicitly for tools. Due to the nature of Linux with the number of kernels
that can exist, we provide source for the driver module and an install script
to build/install it.

The tools support Linux distributions based on kernels 2.6.x. Validation is
done randomly on popular distributions such as Red Hat* or Suse*. Configured
kernel source that matches the currently installed kernel is required. A
working GCC is also required. There are some versions of GCC that had a bug
which did not support unnamed structures. These versions of GCC are not
supported. If you have compilation errors, try updating your version of GCC. If
you have linker errors when installing the driver, you should update your
kernel - download the latest stable off www.kernel.org and build/install it.

Note that some distributions such as recent Fedora core versions do not ship
with Kernel source. You must download, install, and configure the source in
order to get the tools' driver built on this OS. Installing the kernel source
RPM does not solve the problem.

On kernel 4.16 or higher ensure iomem parameter set to relaxed
--------------------------------------------------------------
On kernel 4.16 or higher, the iomem parameter is set to "strict" by default,
which prevents the NVM update utilities from accessing the MMIO of the device.
To fix this, set the iomem kernel parameter to "relaxed" (i.e., iomem=relaxed)
and reboot the system before running the tool. If you run these utilities
without changing the iomem parameter and rebooting first, you will get an error
"The selected adapter cannot be updated due to strict MMIO memory settings in
the kernel."

This is the installation procedure:
  1. Log in as root and create a temporary directory to build the Intel(R)
     Network Connection Tools driver.
  2. Copy 'install' and 'iqvlinux.tar.gz' to the temporary directory.
     There are 3 versions of Linux supported: Linux32 (x86), Linux_x64 (x64),
     and Linux64 (Itanium). Copies of the above files exist in the appropriate
     directory for your platform.
  3. CD to the temporary directory and run './install.' The driver has been
     installed now, so the files in the temporary directory can be removed.
  4. Copy the tools that you want to use from the appropriate directory of
     the CD.


INSTALLING THE TOOLS ON ORACLE* SOLARIS*
========================================
Iqvsolaris is a separate driver used explicitly for tools and is provided only
in binary form. Iqvsolaris driver and tools are provided for 2 different
architectures: 64s for sparc and 64e for x86_64.

In order to run tools on Solaris*, peform the following steps:

  1. Log in as root.

  2. Manually unload the network device driver.

  3. Copy the binary iqv driver to the local machine driver directory by
     running the './install' script.


INSTALLING THE TOOL ON FreeBSD*
===============================

In order to run this tool on FreeBSD*, the base driver must be installed on the
system.


CUSTOMER SUPPORT
================
- Main Intel web support site: http://support.intel.com

- Network products information: http://www.intel.com/network


Legal / Disclaimers
===================
Copyright (C) 2015-2018, Intel Corporation. All rights reserved.

Intel Corporation assumes no responsibility for errors or omissions in this
document. Nor does Intel make any commitment to update the information
contained herein.

Intel and the Intel logo are trademarks of Intel Corporation or its
subsidiaries in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others.

This software is furnished under license and may only be used or copied in
accordance with the terms of the license. The information in this manual is
furnished for informational use only, is subject to change without notice, and
should not be construed as a commitment by Intel Corporation. Intel Corporation
assumes no responsibility or liability for any errors or inaccuracies that may
appear in this document or any software that may be provided in association
with this document. Except as permitted by such license, no part of this
document may be reproduced, stored in a retrieval system, or transmitted in any
form or by any means without the express written consent of Intel Corporation.