Intel® Ethernet NVM Update Tool

Intel® Ethernet Adapters and Devices User Guide

ID	Date	Version	Classification
705831	08/30/2024		Public

Overview

The Intel® Ethernet NVM Update Tool is a utility for updating the non-volatile memory (NVM) of Intel® Ethernet devices. It can also update the PHY firmware (FW) on some devices.

Supported Operating Systems

Microsoft* Windows*
Microsoft Windows Server*
Linux* Kernel
Red Hat* Enterprise Linux*
SUSE* Linux Enterprise Server
openEuler* for AArch64 (only on Intel® Ethernet E810 Series)
UEFI
VMware* ESXi*
FreeBSD*

Note:

On systems running Linux, FreeBSD, or ESXi, the base driver must be present for the Intel Ethernet NVM Update Tool to function correctly.
On Microsoft Windows systems, if the driver required to run the tool is not present on the system, it will automatically be installed when the Intel Ethernet NVM Update Tool is run.

Available Modes

The Intel Ethernet NVM Update Tool operates in one of these modes, which are described in the following subsections:

Interactive mode
Inventory mode
Update mode

Interactive Mode

Interactive mode provides an interactive session of the Intel Ethernet NVM Update Tool. Enter Interactive mode by not specifying the -u or -i parameters when you run the Intel Ethernet NVM Update Tool. All other parameters work with Interactive mode.

Interactive mode runs an inventory on the system and displays the available devices. You can then follow the prompts to specify which device or devices to update.

Inventory progress and debug information are not provided by default. These can be logged to a file by specifying the -l <filename> option or displayed on the console (if no file name is specified).

Note:

A configuration file named nvmupdate.cfg must be present in the same directory as the Intel Ethernet NVM Update Tool for Interactive mode to function correctly.

Inventory Mode

Inventory mode attempts to discover all Intel Ethernet devices present in the system and report the status of each device found. The Intel Ethernet NVM Update Tool performs an integrity check on each device’s NVM image to determine whether a correct image (i.e., valid pointers and checksum) is present. If you specify a configuration file, Inventory mode will only attempt to discover those devices listed in that configuration file. Inventory mode will also report whether an update to the current NVM image is available.

Inventory progress and debug information are not provided by default. These can be logged to the file by specifying -l <filename> option or displayed on the console (if no file name provided).

Inventory mode writes the following information to the XML-formatted results file:

Vendor ID - The vendor ID (typically 8086) in hexadecimal format
Device ID - The device ID in hexadecimal format
Subdevice ID - The subdevice ID in hexadecimal format
Subvendor ID - The subvendor ID in hexadecimal format
Bus - PCI numbered bus identifier
Dev - PCI numbered device identifier
Function - PCI numbered function identifier
Name - Branding string for the device
EEPROM/NVM - EtrackID version
ID EEPROM - ID EEPROM version
OROM - subcomponents and version
Module type - Displays whether a PHY NVM update is available
Update availability - Displays whether an NVM update is available
LAN MAC Address
SAN MAC Address
Alternative MAC Address
Vital Product Data (VPD) variables in a Key:Value format
SREV - The module’s security revision number in hexadecimal format
MinSREV - The module’s minimum security revision number in hexadecimal format

Note:

SREV and MinSREV values will only be captured if -optinminsrev is specified in the command line or if MINSREV:TRUE is specified in the configuration file.

Update Mode

Update mode attempts to discover all devices listed in the configuration file. You must specify a configuration file in order to use Update mode. For each discovered device, the Intel Ethernet NVM Update Tool compares the currently installed NVM image version with a list of update versions in the configuration file. An update is only applied if a newer image is available (with some exceptions described later). The Intel Ethernet NVM Update Tool writes the status of the update (success or failure) to the results file.

The Intel Ethernet NVM Update Tool only updates the entire EEPROM/NVM image. It does not update specific bits/words. Vital Product Data (VPD), end-user, and device-specific data are preserved.

For each device specified in the configuration file, Update mode writes the Inventory mode information (listed previously) to the results file, plus the following:

Version - the reported NVM version is the post-update version
Status - update success or failure

Note:

Interrupting the update process may damage your device.

Firmware Recovery Mode

When a device is in Firmware Recovery mode it will not pass traffic or allow any configuration; you can only attempt to recover the device’s firmware. A device will enter Firmware Recovery mode if it detects a problem that requires the firmware to be reprogrammed.

Note:

Before starting the recovery process, make sure that your operating system, drivers, and tools have been installed properly. You must use the out-of-tree driver. Using the in-box or kernel driver may result in a “Cannot initialize port” warning.
You must power cycle your system after using Recovery Mode to completely reset the firmware and hardware.

See Firmware Recovery Mode in the Device Features section of the user guide for more information.

Pending Reboot State

When a device is in the Pending Reboot state, it is waiting for a system reboot. You cannot modify or update a device when it is in the Pending Reboot state. A device may enter the Pending Reboot state after an NVM update.

Firmware Minimum Security Revision

Many Intel Ethernet devices support a Security Revision (SRev) and a Minimum Security Revision (MinSRev). The Intel Ethernet NVM Update Tool allows you to view or update the MinSRev on supported devices.

See Firmware Security in the Device Features section in the user guide for additional background on these features.

Updating Multiple Devices Concurrently

You can use the -location command line parameter to run multiple instances of the tool, each updating a specific device. You must use the -location parameter with either the -u or -i parameter. The -location parameter is not available in Interactive mode.

Updating Intel® Ethernet 800 Series Devices in a Linux System

This applies to Intel® Ethernet 800 Series devices in systems running Linux Stable Kernel 5.1 (and above), RHEL 8 (and above), and SLES 15 (and above) with the inbox driver. For devices in these situations, the Intel Ethernet NVM Update Tool will use the devlink interface to update the device NVM. In this situation, the -p command line parameter (suppress update of the OROM) does not function.

You can force the tool to use the ioctl or devlink interface by specifying -if vendor or -if devlink in the command line. However, the ioctl interface is available only with the out-of-tree driver. See the -if <interface> parameter description below for more information.

For example:

# nvmupdate64e -u -p -l nvmupdatelog.txt -c nvmupdate.cfg -if vendor

# nvmupdate64e -u -p -l nvmupdatelog.txt -c nvmupdate.cfg -if devlink

Updating the NVM with a DPDK Driver

If all of the following are true:

You want to update or inventory one of the following:
- Devices based on the Intel® Ethernet 800 Series
- Devices based on the Intel® Ethernet 700 Series
You are using the DPDK driver
The i40e/ice device driver is not bound to any port on the device.

Then you must do the following:

Bind the kernel driver to the device.
- Make sure the i40e/ice kernel driver is installed.
- Use lspci to discover the PCI location of the device port you want to update/inventory (in <Bus:Device.Function> format (e.g. 04:00.0))
- Bind the port with the kernel driver:
```
usertools/dpdk-devbind.py -b <i40e|ice> <B:D.F>
```
Run Nvmupdate.
- Update mode example:
```
nvmupdate -u -l -c nvmupdate.cfg
```

Inventory mode example:
```
nvmupdate -i -l -c nvmupdate.cfg
```

Reboot the system, if required.
Restore your initial driver configuration by loading the DPDK driver:
```
usertools/dpdk-devbind.py -b igb_uio <B:D.F>
```

Running the Utility

Use the following syntax to run the Intel Ethernet NVM Update Tool:

nvmupdate [options]

Using the /? option will display a list of supported command line options.

When running the utility, take note of the following:

Progress and debug information are not provided by default.
- Specify -l <filename> to send progress and debug information to a log file.
- Specify -l without a filename to send the information to the console.
More than one update may be required to bring your device’s NVM fully up to date. In this situation, the tool will display and log a message indicating that another update is required.
If both an NVM image and an FLB file are provided for the update, the OROM update will come from the FLB file.
The Intel Ethernet NVM Update Tool supports using a PLDM package as the update image. If the PLDM package contains more than one NVM image, the tool will not apply the update and will exit with error code 23.
Some Intel® Ethernet Converged Network Adapter X710-T4 adapters may display the message “Image differences found at offset 0x7…” when performing an update using the 700 Series NVM Update Package. This behavior is expected. Updating the Option ROM on a device with Device ID 1586 is a two-step process. The first update will change the Device ID to 1589. Reboot your system and run the update tool a second time to update the Option ROM for the new Device ID.
If the tool indicates that a power cycle is required, make sure that your system powers off completely. A system reset or soft power cycle will result in an incomplete update. We recommend you disconnect the power cable for 30 seconds to ensure a complete power off.
During an inventory operation, you may see link temporarily dropped until the Intel Ethernet NVM Update Tool completes its current operation. This is because the PHY controller is stopped to avoid issues when the tool accesses the PHY NVM interface.
If recovery is requested but there are no devices in recovery mode, the Intel Ethernet NVM Update Tool will return success.
On a system running VMWare ESXi 6.5 and later, while Secure Boot Mode is enabled, the Intel Ethernet NVM Update Tool cannot be run from datastores. If Secure Boot is enabled, you can run the Intel Ethernet NVM Update Tool from the /tmp directory. Or you can disable Secure Boot, run the Intel Ethernet NVM Update Tool, and then re-enable Secure Boot.

Command Line Parameters

When run with no parameters, the Intel Ethernet NVM Update Tool runs in Interactive mode.

Note:

The -i and -u parameters are mutually exclusive; do not use both parameters at the same time.

-h, -?: Display command line usage help.

-a <path>: Specify a path for all file operations. The path is applied to all operations (such as locating the configuration file and NVM images, as well as where the log file and results file will be generated). Any path specified in the config file will be appended to the -a path. This parameter is used only with the -i or -u parameters.
-b: Save a backup copy of the current NVM image(s). The NVM Update tool creates a subdirectory using the device(s) MAC address as the directory name and stores the backup files there. Use this parameter only with the -u parameter.
-c <file name>: Specify the name of the configuration file. This is a text file that contains descriptions of networking devices and firmware versions for those devices. The syntax of the configuration file can be found in the Configuration File Syntax section below. If -c is not specified, nvmupdate.cfg is used. If you do not specify a config file, nvmupdate.cfg must be present in the same directory as the Intel Ethernet NVM Update Tool for Interactive mode to function correctly.
-f: Force the NVM update. The tool will skip binary verification and apply the update even if the image version is the same.
-i: Inventory mode. Lists the devices in the system and indicates the status of each device.

-if <interface>: Force the tool to use the specified driver interface. Supported values for <interface> are: vendor and devlink. If vendor is used, the tool uses the ioctl interface.
Note:
The ioctl interface is available only with the out-of-tree driver.

-l <file name>: Specify the name of the log file. This is a text file that contains a history of the Intel Ethernet NVM Update Tool’s execution, including the success or failure status for each operation, and what adapters and OROMs were discovered. The log file is overwritten each time the Intel Ethernet NVM Update Tool is executed. If no file name is specified, the log messages are displayed on the system console.

-location <SS:BBB>: Specify a device for this instance of the tool to update, where SS is the PCI segment of the desired device and BBB is the PCI bus of the desired device. You cannot run multiple instances of the tool on a specific device.
Note:
-location must be used with the -i or -u parameter.

-m <MAC address>

Update only the device with the specified MAC address. This is the LAN MAC address, not the SAN or AltMAC address.

Note:

The device must have an entry in the configuration file.

-o <file name>

Specify the name and path of the results file. This is an XML file that contains the inventory/update results. If no file name is specified, the inventory/update results are displayed on the system console. Like the log file, the results file is overwritten each time the Intel Ethernet NVM Update Tool is executed.

-optinminsrev

In Update mode, -optinminsrev sets the minimum security revision of the NVM that is allowed to be installed on all devices defined in the configuration file, even if MINSREV is set to FALSE or is missing for a device. If -optinminsrev is not specified, only devices that have MINSREV set to TRUE in the configuration file will have their minimum security revision increased.

In Inventory mode, displays the device’s SRev and MinSRev values in the results XML file.

Note:

-optinminsrev must be used with the -c parameter.

-p

Keep existing option ROM image (suppress update of the OROM).

-r

Rollback mode. Must be used with the -m parameter. You must have previously created a backup with the -b parameter for a restore point. The Intel Ethernet NVM Update Tool blocks rollback if the restore point NVM version is too old or does not contain critical updates.

-rd

Reset user settings to default values during update.

-RecoveryDevices

Must be used only with the -i or -u parameters. If you specify -i -RecoveryDevices, only devices in recovery mode will be displayed. If you specify -u -RecoveryDevices, only devices in recovery mode will be updated.

-s

Silent mode. Specifying this option will suppress all output to the display. The Intel Ethernet NVM Update Tool output is limited to the results file and the logfile.

-sv

Skip image verification.

-u

Update mode. Updates the devices in the system. You must provide a configuration file to use update mode.

-UpdateDevices

Must be used only with the -i or -u parameters. Ignores devices in recovery mode during update. If you specify -i -UpdateDevices, devices in recovery mode will not be displayed. If you specify -u -UpdateDevices, devices in recovery mode will not be updated.

-v

Display the version of the QV SDK and Ethernet driver installed in the system (base driver for Linux, FreeBSD, ESXi, and QV driver for Windows).

Command Line Examples

For these examples, enter Inventory mode and capture the status to a log file.

On an x64 Microsoft Windows system, type:

nvmupdatew64e -i -l nvmupdatelog.txt

On an x64 Linux system, type:

nvmupdate64e -i -l nvmupdatelog.txt

Example Inventory output:

Num Description                        Ver.(hex)    DevId  S:B     Status
=== =================================  ===========  =====  ======  ================
1)  Intel(R) Ethernet Connection X722               37CC   00:004  Recovery Mode
2)  Intel(R) Ethernet 10G 2P X550-t    1.32(1.20)   1563   00:007  Update available
    Adapter

For these examples, enter inventory mode and capture only devices in recovery mode to a log file.

On an x64 Microsoft Windows system, type:

nvmupdatew64e -i -RecoveryDevices nvmupdatelog.txt

On an x64 Linux system, type:

nvmupdate64e -i -RecoveryDevices nvmupdatelog.txt

Example Inventory output:

Num Description                       Ver.(hex)    DevId  S:B     Status
=== ================================= ===========  =====  ======  ================
01) Intel(R) Ethernet Connection X722              37CC   00:004  Recovery Mode

For these examples, enter Inventory mode and capture only devices with updates available to a log file.

On an x64 Microsoft Windows system, type:

nvmupdatew64e -i -UpdateDevices nvmupdatelog.txt

On an x64 Linux system, type:

nvmupdate64e -i -UpdateDevices nvmupdatelog.txt

Example Inventory output:

Num Description                        Ver.(hex)   DevId  S:B   Status
=== ================================== =========== ===== ====== ================
02) Intel(R) Ethernet 10G 2P X550-t    1.32(1.20)  1563  00:007 Update available
    Adapter

For these examples, enter interactive mode and display output and status to the screen.

On an x64 Microsoft Windows system, type:

nvmupdatew64e -l

On an x64 Linux system, type:

nvmupdate64e -l

For these examples, enter Update mode and specify a log file and configuration file.

On an x64 Microsoft Windows system, type:

nvmupdatew64e -u -l nvmupdatelog.txt -c nvmupdate.cfg

On an x64 Linux system, type:

nvmupdate64e -u -l nvmupdatelog.txt -c nvmupdate.cfg

Example Update output:

Num Description                        Ver.(hex)   DevId  S:B   Status
=== ================================== =========== ===== ====== ===================
1)  Intel(R) Ethernet Converged        6.01(6.01)  1521  00:001 Rollback Blocked
    Network Adapter XL710-Q2
2)  Intel(R) Ethernet 10G 2P X550-t    1.32(1.20)  1563  00:007 Update successful
    Adapter
3)  Intel(R) Ethernet Controller X540  4.04(4.04)  1560 00:132  Access error
4)  Intel(R) Ethernet Connection X722              1560 00:132  RECOVERY successful
    for 10GbE SFP+

Exit Codes

Upon exit, when possible, the Intel Ethernet NVM Update Tool reports an overall status code to indicate the results of the operation. In general, a non-zero return code indicates an error occurred during processing.

Value	Description
0	All operations completed successfully.
1	General tool execution error.
2	The configuration file could not be opened/read, or a syntax error was discovered in the file.
3	The inventory process failed.
4	A file error occurred when accessing the results file.
5	Bad command line parameter.
6	An error occurred when updating a firmware module.
7	A file error occurred when creating/writing the log file.
8	An error occurred accessing the device.
12	The EEPROM MAP file could not be opened/read, or a syntax error was discovered in the file.
15	Another instance of the Intel Ethernet NVM Update Tool is already running.
18	An error occurred during reset.
19	Device not found.
20	Communication with base driver failed. Please verify that the base driver is present.
21	Unsupported NVM image discovered. Please upgrade to the latest version of the Intel Ethernet NVM Update Tool.
22	The image backup process failed.
23	The requested image cannot be applied over the existing NVM content. Please download the most recent update package and retry the update.
24	Cannot restore manufacturing data.
25	Update stopped due to Rollback Revision mismatch. The Intel Ethernet NVM Update Tool blocks rollback if the restore point NVM version is too old or does not contain critical updates.
26	The selected adapter cannot be updated due to strict MMIO memory settings in the kernel. Set the iomem kernel parameter to relaxed and reboot the system before running this utility again. Consult the utility documentation for more information.
30	MINSREV update failed. The minimum security revision was not set for the device.
31	Image prerequisite check failed.
35	The tool cannot find the correct preservation rules in the NVM on the device. User settings cannot be preserved with this update. To update the NVM, overwrite the user settings by using the -rd switch.
36	Parallel execution of Intel Ethernet NVM Update Tool for this device is not allowed. Either there is already an instance of Intel Ethernet NVM Update Tool running on this device or the device does not support the -location parameter.
37	Requested image cannot be applied over existing NVM content. Please download the most recent update package and retry update.
38	NVM update functionality is not supported on this device using this driver. Please download the latest driver.
39	NVM update functionality in recovery mode is not supported on this device using this driver. Please download the latest driver.
40	Individual updates are not supported on this device using the kernel driver. Please download the latest driver.
41	The base driver does not support the requested feature.
50	Please perform the indicated reset action and run the Intel Ethernet NVM Update Tool again to complete the update.
51	Update available for one or more adapters.

Note:

EFI versions of this tool may report an incorrect error code when no adapter is installed. This is due to a known limitation in the UDK2015 UEFI Development Kit (UDK) build environment.

Configuration File

The configuration file is a text file containing a short header followed by a series of device blocks. The device blocks contain a series of tag:value pairs, each of which describes an Intel networking device and specifies approved versions of firmware for that device.

The Intel Ethernet NVM Update Tool checks a device to see if it is a candidate for update. The check matches on the following fields:

EtrackId (from the REPLACES field) + VENDOR + DEVICE + SUBVENDOR + SUBDEVICE
EtrackId (from the REPLACES field) + VENDOR + DEVICE
VENDOR + DEVICE + SUBVENDOR + SUBDEVICE
EtrackId (from the REPLACES field) + VENDOR + DEVICE + SUBVENDOR + SUBDEVICE + PBA
EtrackId (from the REPLACES field) + VENDOR + DEVICE + PBA
VENDOR + DEVICE + SUBVENDOR + SUBDEVICE + PBA

Restrictions and Rules

You cannot update the EEPROM and the NVM in the same session. Only one should be specified in the configuration file.
You can update the EEPROM and the OROM in the same session. The EEPROM will be updated first, followed by the OROM.
You can update the NVM and the OROM in the same session. The NVM will be updated first, followed by the OROM.
Inventory mode does not consider potential EEPROM/NVM image changes if a sequential OROM update is requested (e.g. an additional reboot might be required).
On multiport adapters, due to there being only one EEPROM/flash that is shared by all ports, only port 0 will be updated (or the port with the MAC address specified with the -m command line parameter).
Blank lines or lines beginning with a semicolon (comments) are ignored.
Unrecognized keywords in the configuration file will result in the NVM Update tool exiting abnormally and reporting a syntax error (exit code=2). Run the NVM Update tool again, with the Enable Logging command line parameter (-l), to see what specific line is in error.
An OROM update is allowed only if the specified OROM component set matches combo rules (the vendordevice pairs defined in the .flb file).
An OROM downgrade is allowed only if a value of TRUE is assigned to the OROM DOWNGRADE key.
If the configuration file specifies the OROM IMAGE field, but does not specify any OROM components (PXE, EFI, etc.), the device’s current set of OROM components is used as the component list.
An OROM update preserves the current configuration of components, or resets the configuration to the default if new settings do not allow for configuration preservation (e.g., when combo rules differ).
EtrackId of EEPROM or NVM and OROM components version values specified in the configuration file are compared against values stored in .eep/.bin or .flb files. If a mismatch is found, the inventory/update is aborted.
If the EtrackId of EEPROM or NVM and OROM components version values are not specified in the configuration file, then values from .eep/.bin or .flb are taken without verification.
EEP/NVM/OROM update is always allowed if running image versions cannot be specified or are invalid.
EEPROM/NVM downgrade is allowed only when the REPLACES key is specified with an active EtrackID value.
A candidate match based on sub IDs requires that both SUBVENDOR and SUBDEVICE fields are present in the configuration file.
If the REPLACES field is not present, you must include the SUBVENDOR and SUBDEVICE fields in the configuration file. SUBVENDOR and SUBDEVICE are optional if REPLACES is present.
The Intel Ethernet NVM Update Tool will not report errors for devices that are not specified in the config file.
If recovery is requested but there are no devices in recovery mode, the NVM Update tool will return success.

Configuration File Syntax

All configuration file fields are required, except for those indicated as “[Optional]”.

See Configuration File Examples below for examples of this syntax in practice.

CURRENT FAMILY: <version>

[Optional] Defines OEM version (x.y.z) for the file.

CONFIG VERSION: <version>

Defines the version of the configuration file format in use. The parameter is in the format <x.y.z>.

BEGIN DEVICE

Demarcates the start of a device definition block.

DEVICENAME: xxxx

[Optional] The branding string of the device. This is only used to make the file easier to read; it is not processed by the tool.

VENDOR: xxxx

The vendor ID, typically 8086, in hexadecimal.

DEVICE: xxxx

The device ID number, in hexadecimal. You can specify more than one device ID, separated by spaces.

SUBVENDOR: xxxx

The subvendor ID number, in hexadecimal. You can specify more than one subvendor ID, separated by spaces.

SUBDEVICE: xxxx

The subdevice ID number, in hexadecimal. You can specify more than one subdevice ID, separated by spaces.

REVISION: xxxx

[Optional] The revision number, in hexadecimal. If not provided, revision numbers of all devices in the system will be considered to match configuration file definitions.

CURRENT GFID: <GFID number>

[Optional] If specified, this value must match the CURRENT GFID value on the update image for the update to proceed. If CURRENT GFID is not specified, but ORIGINAL GFID is, then nvmupdate will use the ORIGINAL GFID value in both cases. If neither is specified, then the <GFID number> value will be taken directly from the image in the .flb file and compared to the device. Specifying a CURRENT GFID value reduces the number of .flb file reads, which reduces the time required for the update to complete.

ORIGINAL GFID: <GFID number>

[Optional] If specified, this value must match the ORIGINAL GFID value on both the pre-update device and the update image for the update to proceed. If ORIGINAL GFID is not specified, but CURRENT GFID is, then nvmupdate will use the CURRENT GFID value in both cases. If neither is specified, then the <GFID number> value will be taken directly from the image in the .flb file and compared to the device. Specifying an ORIGINAL GFID value reduces the number of .flb file reads, which reduces the time required for the update to complete.

GFID EXACT: <TRUE/FALSE>

[Optional] If specified, only devices that exactly match the GFID (origin and current) will be updated.

MINSREV: <TRUE/FALSE>

[Optional] In Update mode, sets the minimum security revision of the NVM that is allowed to be installed on the device. If set to TRUE, sets MINSREV to the SREV value of the firmware currently installed on the device (This is set after the update, if an update is specified in the configuration file). If set to FALSE, or not included, the MINSREV value is not changed.

In Inventory mode, displays the device’s SRev and MinSRev values in the results XML file.

PBA: <pba_number>

[Optional] The PBA number, in either the first six characters of the PBA (123456) or the full PBA (123456-000) form. If PBA is not provided, then all devices in the system are considered to match configuration file definitions.

PXE: <version>

[Optional] The version number (x.xx.xx), in decimal format, for the PXE firmware subcomponent. The string NONE (or value 0.0.0) indicates that PXE should not be installed on this device. If <version> is not specified, then the value is taken directly from the .flb file.

EFI: <version>

[Optional] The version number (x.xx.xx), in decimal, for the EFI boot firmware subcomponent. The string NONE (or value 0.0.0) indicates that EFI should not be installed on this device. If <version> is not specified, then the value is taken directly from the .flb file.

EFI_IA64: <version>

[Optional] The version number (x.xx.xx), in decimal, for the EFI IA64 boot firmware subcomponent. The string NONE (or value 0.0.0) indicates that EFI_IA64 should not be installed on this device. If <version> is not specified, then the value is taken directly from the .flb file.

ISCSI: <version>

[Optional] The version number (x.xx.xx), in decimal, for the iSCSI boot firmware subcomponent. The string NONE (or value 0.0.0) indicates that iSCSI boot should not be installed on this device. If <version> is not specified, then the value is taken directly from the .flb file.

SMCLP: <version>

[Optional] The version number (x.xx.xx), in decimal, for the SMCLP firmware subcomponent. The string NONE (or value 0.0.0) indicates that SMCLP should not be installed on this device. If <version> is not specified, then the value is taken directly from the .flb file.

OROM IMAGE: <filename>

The name of the file that contains OROM components for this device (typically an .flb file).

OROM DOWNGRADE: <TRUE/FALSE>

[Optional] If set to TRUE, allows the option ROM image to be downgraded to a previous version. OROM DOWNGRADE permission is set to FALSE by default.

SKIP OROM: <TRUE/FALSE>

[Optional] If set to TRUE, keeps the existing option ROM image (suppresses update of the OROM).

EEP IMAGE: <filename>

The name of the file containing the EEPROM image for this device (typically an .eep file).

EEPROM MAP: <filename>

[Optional] The name of the text file that contains a list of words to be preserved, overwritten, or excluded from verification by the NVM Update tool. This key is to be part of each device configuration specified within a device block in the configuration file. EEPROM MAP is optional and has no default value. If no value is specified in the key, a configuration file error (exit code 2) is returned. Details regarding the format and content of this text file are given in the EEPROM Map Text File Syntax section below.

BEGIN IDEEPROM: ID=<ideeprom_id>

Demarcates the beginning of an ID EEPROM subsection. ID=<ideeprom_id> is optional and is the OCP_ID of an ID EEPROM image to use for the update in hexadecimal.

An ID EEPROM definition block may contain the following fields:

IMAGE: <filename>
    The file that contains the ID EEPROM image.
  DOWNGRADE: <TRUE|FALSE>
    [Optional] If set to TRUE, allows the ID EEPROM image to
    be downgraded to a lower version. IDEEPROM DOWNGRAGE
    permission is set to FALSE by default.
  VERSION: <version>
    [Optional] the version number of the ID EEPROM image.

END IDEEPROM

Demarcates the end of the ID EEPROM subsection.

NVM IMAGE: <filename>

[Optional] The name of the file that contains the entire NVM image (EEPROM, OROM and FW) for this device (typically a .bin file).

IMAGE DOWNGRADE: <TRUE/FALSE>

[Optional] If set to TRUE, allows the EEPROM or NVM image to be downgraded to a previous version. IMAGE DOWNGRADE permission is set to FALSE by default.

NETLIST IMAGE: <filename>

The name of the file that contains the Netlist module.

NETLIST VERSION: <version>

[Optional] Only used with NETLIST IMAGE. The <version> number is <BRVmajor.BRVminor.BRVrevision.CV>, in decimal, for the Netlist module, where:

BRVmajor:: Base release version, Major
BRVminor:: Base release version, Minor
BRVrevision:: Base release version, Revision number
CV:: Customer version number

NETLIST TYPE: <type>

Type of the associated Netlist module, in decimal.

NETLIST DOWNGRADE: <TRUE/FALSE>

[Optional] If set to TRUE, allows the Netlist module to be downgraded to a previous version. NETLIST DOWNGRADE permission is set to FALSE by default.

SKIP NETLIST: <TRUE/FALSE>

[Optional] If set to TRUE, keeps the existing Netlist module (suppresses update of the Netlist module).

EEPID: xxxx

[Optional] The unique 32-bit ETrack-ID image tag, in hexadecimal.

REPLACES: xxxx

[Optional] EEPID of the old image that the current image replaces. You can specify multiple old images by separating them with a space. Used to handle customized NVM settings that may have the same vendor and device ID information as other devices (for driver compatibility reasons) but need specific update files. If not present, then the section will wildcard match on the listed VENDOR, DEVICE, and SUBSYSTEM ID fields.

MODE: <device_mode>

[Optional] List of modes which are supported by the device. If MODE is not specified, devices that have a valid update or are in recovery mode will all be updated. Valid values for <device_mode> are:

UpdateDevices:: Ignore devices in recovery mode.
RecoveryDevices:: Only update devices in recovery mode.

RESET TYPE: <reset_type>

[Optional] The type of reset required after updating the EEPROM. Allows the developer of the EEPROM package to specify the correct reset type. RESET TYPE is ignored if the device’s EEPROM is not updated (i.e., Option ROM update only). Valid values for <reset_type> are:

NONE:: No reset required.
PHY:: PHY reset for 10G and 40G adapters. This reset issue executed only if the PHY NVM or PHY module was updated.
HICR:: Firmware reset (initiated by software) that is only usable on HICR enabled devices. This reset is executed only if the EEPROM was updated (1G and 10G adapters) or if the MAC NVM was updated (10G adapters).
BMC:: Firmware reset initiated by the BMC via SMBus or NC-SI. The tool tells the user to reset the device via BMC or a power cycle of the system.
DELAYED_REBOOT:: The device will not load and run the update until your system is rebooted. Once the system is rebooted, the update will load on the device.
REBOOT:: The tool tells the user to reboot the system (only if the NVM/EEPROM was updated). This reset type is supported on all devices.
POWER:: The tool tells the user to power cycle the system (only if the NVM/EEPROM was updated). This reset type is supported on all devices.

You can specify more than one RESET TYPE per device. If more than one type is specified, and the conditions are met for more than one type, only the reset with the highest priority will be executed:

POWER has the highest priority.
REBOOT has the second highest priority.
DELAYED_REBOOT, BMC, HICR, and PHY all share the lowest priority.

PHY DOWNGRADE: <TRUE/FALSE>

[Optional] If set to TRUE, allows the PHY NVM image to be downgraded to a lower version. PHY DOWNGRADE permission is set to FALSE by default.

SKIP PHY: <TRUE/FALSE>

[Optional] If set to TRUE, keeps the existing PHY NVM image (suppresses update of the PHY NVM).

PHY IMAGE: <filename> <phy_family>

The name of the file that contains the PHY FW image for this device followed by the PHY family ID. The PHY family ID is compared to the device’s NVM. The PHY FW will only update if the values match.

PHY VERSION: <version> <filename>

[Optional] The version number of the PHY NVM contained in <image file>.

BEGIN PHY: ID=<phy_id> , FAMILY=<phy_family>

Demarcates the beginning of a PHY definition block, where:

ID=<phy_id>:: The PHY ID in hexadecimal.
Family=<phy_family>:: The PHY Family ID in hexadecimal.

The PHY ID and PHY Family ID are compared to the device’s NVM. The PHY FW will only update if the values match.

A PHY definition block may contain the following fields:

DOWNGRADE: <TRUE/FALSE>: [Optional] If set to TRUE, allows the PHY NVM image to be downgraded to a lower version. PHY DOWNGRADE permission is set to FALSE by default.
IMAGE: <filename>: The name of the file that contains the PHY FW image for this device.
VERSION: <version>: [Optional] The version number of the PHY NVM.

END PHY

Demarcates the end of a PHY definition block.

RO IMAGE: <filename>

The name of the file that contain RO module image for the device.

RO VERSION: <version>

The version number for the RO module, in hexadecimal format.

FEATURES: <feature>

[Optional] Device features which cannot be detected by the Intel Ethernet NVM Update Tool. Valid values for <feature> are:

DOUBLE_REBOOT_GPIO{n}:: The device circuit handling a double reboot using GPIO{n} (where {n} is an integer value from 0 to 5).

FORCE UPDATE: <TRUE/FALSE>

[Optional] If set to TRUE, updates the device regardless of the Pending Reboot state. If excluded or set to FALSE, will only update the device if it is not in Pending Reboot.

PRESERVATION: <preservation_type>

How much of the Preserved Field Area (PFA) is kept during the update.

Valid values for <preservation_type> are:

FULL:: No change to current PFA
SELECTIVE:: Preserves selected fields in current PFA
MANUFACTURING DEFAULTS:: Replace PFA with values from manufacturing defaults module
NONE:: No preservation (firmware overwrites current PFA with the default PFA from the image)

END DEVICE

Demarcates the end of a device definition block.

Configuration File Examples

The following is an example of a configuration file with one device block:

CURRENT FAMILY: 12.1.1
CONFIG VERSION: 1.7.0

BEGIN DEVICE
  DEVICENAME: Intel x540 Adapter
 VENDOR: 8086
 DEVICE: 10C9
 SUBVENDOR: 8086
 SUBDEVICE: A04C
 REVISION: 2
 PXE: 1.3.04
 EFI: 2.7.06
 ISCSI: 3.8.17
 SMCLP: 5.8.17
 NVM IMAGE: nvmImage.bin
 OROM IMAGE: BootImg.flb
 EEPID: 800007A9
 REPLACES: 80000692
 EEPLAYOUT: 82599
 RESET TYPE: POWER
END DEVICE

The following is an example of a device block with multiple device IDs:

BEGIN DEVICE
 VENDOR: 8086
 DEVICE: 37D1 37D2 37D3
 SUBVENDOR: 8086
 SUBDEVICE: 0
 NVM IMAGE: nvm_image.bin
END DEVICE

EEPROM Map Text File Syntax

See EEPROM MAP File Example below for examples of this syntax in practice.

EEPROM MAP FILE VERSION: 1.1.0

This version number will be used to find any mismatch between the NVM Update tool and EEPROM MAP file version. This is the only obligatory field in the file.

Data in the file are divided into 3 major blocks:

PRESERVE
VERIFICATION EXCLUDED
OVERWRITE

Data from PRESERVE and VERIFICATION EXCLUDED blocks are excluded from image comparison. Image comparison occurs when the same version of the image is found on the device and in the files provided for the inventory/update, and after an update to verify if written image matches provided one. The comparison recognizes if the current image is corrupted. If the same set of data is provided in the PRESERVE and OVERWRITE blocks, data from OVERWRITE takes precedence. All PRESERVE actions occur before OVERWRITE actions, regardless of where they are in the map file.

There is no conflict if the same data are provided in VERIFICATION EXCLUDED and either PRESERVE or OVERWRITE blocks.

PRESERVE and VERIFICATION EXCLUDED blocks

Within the PRESERVE and VERIFICATION EXCLUDED blocks, multiple sections of the same type definition may be included. The following blocks are analyzed:

DIRECT - <offset> <bitmask> <count>

Section containing words’ addresses. Data in this section (separated by white spaces) consist of:

<offset>:: word offset, e.g. “0x2E”
<bitmask>:: word bitmask, e.g. “0xFFFF”
<count>:: consecutive number of words, e.g. “1”

POINTER - <pointer> <offset> <bitmask> <count>

Section containing pointers and offsets. Data in this section (separated by white spaces) consist of:

<pointer>:: pointer address to selected area, e.g. “0x07”
<offset>:: word offset, e.g. “0x01”
<bitmask>:: word bitmask, e.g. “0xFFFF”
<count>:: consecutive number of words, e.g. “3”

DOUBLE POINTER - <pointer> <pointer offset> <offset> <bitmask> <count>

Section containing pointers, second level pointer offsets and third level offsets. Data in this section (separated by white spaces) consist of:

<pointer>:: pointer address to selected area (module pointer), e.g., “0x07”
<pointer offset>:: pointer offset (value calculated as a relative to module pointer), e.g. “0x02”
<offset>:: word offset, e.g. “0x0A”
<bitmask>:: word bitmask, e.g. “0xFFFF”
<count>:: consecutive number of words, e.g. “1”

TLV - <TLV type>

Section containing TLVs to be preserved, where:

<TLV type>:: TLV type (hex), e.g. “1A2B”

VPD

Section may contain one major VPD subsection (this subsection is optional and may be omitted):

ALL:: If set, preserves the VPD content during a recovery operation. This value is only for use if the device is in recovery mode. It will not affect normal operations.

OVERWRITE block

If values (and colons) are not provided in the below sections of the OVERWRITE block, the value from the NVM image is used for update. This is the desired way to exclude selected VPD areas from being preserved.

The EEPROM MAP file may contain comments after a “;” (semicolon). Each block and section needs to have BEGIN and END statements. If the file referenced in the configuration file is not provided, or the data in the file is of the wrong format, the Intel Ethernet NVM Update Tool will exit with exit code EEPROM MAP FILE ERROR (exit code: 12). If the file contains only the file version with no other definitions, the file is skipped.

The OVERWRITE block should contain blocks and sections with values:

DIRECT - <offset><value>

Section containing words’ addresses and their values. Data in this section consist of:

<offset>:: word offset, e.g. “0x2E”
colon (:):: (optional)
<value>:: value (hex), e.g. “1A2B” (optional)

POINTER - <pointer> <offset><value>

Section containing pointers, offsets, and their values. Data in this section (separated by white spaces) consist of:

<pointer>:: pointer address to selected area, e.g. “0x07”
<offset>:: word offset, e.g. “0x00”
colon (:):: (optional)
<value>:: value (hex), e.g. “1A2B” (optional)

DOUBLE POINTER - <pointer> <pointer offset> <offset><value>

Section containing pointers, second level pointer offsets and third level offsets. Data in this section (separated by white spaces) consist of:

<pointer>:: pointer address to selected area (module pointer), e.g. “0x07”
<pointer offset>:: pointer offset (value calculated as a relative to module pointer), e.g. “0x02”
<offset>:: offset, e.g. “0x0A”
colon (:):: (optional)
<value>:: value (hex), e.g. “1A2B” (optional)

TLV - <TLV type><TLV_offset>: <value>

Section containing TLVs to be overwritten with new values.

<TLV type>:: TLV type (hex), e.g. “1A2B”
<TLV_offset>:: offset to first word in buffer specified for TAG which should be changed.
colon (:):: (optional)
<value>:: value (hex), e.g. “1A2B” (optional)

VPD - <key><value>

Section may contain three major VPD subsections (these subsections are optional and may be omitted):

READ:
WRITE:
ALL:: If set, does not preserve the VPD content. VPD content will be overwritten.

Data in the READ and WRITE (sub)sections consist of:

<key>:: one of valid VPD fields defined in PCI VPD specification (e.g. PN, EC, SN, Vx)
colon (:):: (optional)
<value>:: value (ASCII), e.g. “FFV13.00.00” (optional)

EEPROM MAP File Example

Example EEPROM MAP file contents with data to be preserved, overwritten, and excluded from comparison:

EEPROM MAP FILE VERSION: 1.0.0
BEGIN PRESERVE
    BEGIN DIRECT
        0x0B 0xFFFF 1    ;Subsystem ID
    END DIRECT
    BEGIN POINTER
        0x37 0x0 0xFFFF 6    ;Alternate MAC address
    END POINTER
    BEGIN DOUBLE POINTER
        0x0C 0x11 0x00 0xFFFF 1
    END DOUBLE POINTER
END PRESERVE
BEGIN VERIFICATION EXCLUDED
    BEGIN DIRECT
        0x38 0x0003 1    ;APM Enable Port
    END DIRECT
    BEGIN POINTER
    0x28 0x0 0xFFFF 6
    END POINTER
END VERIFICATION EXCLUDED
BEGIN OVERWRITE
    BEGIN DIRECT
        0x00 : 001B    ;MAC address
        0x01 : 1234
        0x02 : 5678
    END DIRECT
    BEGIN POINTER
        0x29 0x01 : 1111
    END POINTER
        BEGIN DOUBLE POINTER
        0x0C 0x11 0x00 : ABCD
    END DOUBLE POINTER
    BEGIN VPD
        ALL    ;reset the VPD content
        BEGIN READ
            V1
        END READ
        BEGIN WRITE
            V3 : DTINIC
        END WRITE
    END VPD
END OVERWRITE

Troubleshooting

Note:

If the tool displays an error such as “Access error” or “Cannot initialize port” you may be using an outdated driver. Please download the latest driver from https://support.intel.com and try again.

Note:

If the tool displays the error: “Unable to load the driver. Please close all other applications and try again”, you have a mix of old and new versions of the utility tool on your system. Quit all open applications and retry your operation. If the issue persists:

Download the latest version of the utility tools.
Run the uninstall script to remove the old version of the tool driver.
Run the install script from the downloaded tools package.
Retry your operation.

You may also need to download and install the latest Intel Ethernet driver or Intel® PROSet package for your device.