Index | Thread | Search

From:
Stefan Huber <stefan.huber@stusta.de>
Subject:
firmware update for intel X700 series network cards (2 of 2: user space tool ixlnvm(8))
To:
tech@openbsd.org
Date:
Sat, 07 Nov 2026 13:14:17 +0100

Download raw body.

Thread
Hey all,

in part 1 of 2 of this change, I proposed the kernel interface change
to make NMV updates on Intel network cards possible. This second part
proposes the ixlnvm(8) tool.

How it works (also see man 8 ixlnvm):

1. download current nvm and config from intel and unpack it
2. go to the folder with nvmupdate.cfg and scan:
 `ixlnvm`
 (...)
 ixl0,ixl1  (pci 5:0, 2 ports)
      nvm 9.30  fw 9.130.73618  eetrack 0x8000e5d7  UPGRADE
      upgrade to X710DA2_9p58_CFGID7p2_OEMGEN.bin (reset REBOOT)
      apply:  ixlnvm -i ixl0 image-apply -f
X710DA2_9p58_CFGID7p2_OEMGEN.bin -y
 (...)
4. go to single user mode and apply:
   `ixlnvm -i ixl0 image-apply -f X710DA2_9p58_CFGID7p2_OEMGEN.bin -y`
5. reboot
6. have new nvm:
   `ixlnvm`
   ixl0,ixl1  (pci 5:0, 2 ports)
              nvm 9.58  fw 9.158.79338  eetrack 0x800104df  NO_CFG
7. ???
8. PROFIT!

caveats / shortcomings:
When ice(4) support is added, the tool should be renamed (intel calls
theirs "nvmupdate", so "nvmupdate" or "intel-nvmupdate"?).
When the upgrade process is interrupted (because of a power outage or
kernel panic), the network card might be in an unsupported state, as
with the original intel tool. If the BMC Controller NVM is bricked, the
card boots into failsafe mode and can be repaired via the EFI
"nvmupdate" tool. Any writes for later / other NVM modules fail, and
the card will still boot, but might not function proberly - re-applying
the flash with this tool will fix the card. I've not yet tested this
tool on a "broken" card, but since the datasheet states the card will
be in "recovery" mode, I don't think it will attach via ixl(4), thus
probably not be fixable *right now*. A driver for ixl-failsafe could be
added in the future and could be used with (probably anotherI "intel-
recovery" userspace tool to rewrite the firmware.

Technical stuff / full commit message:

New utility that reads and updates the NVM (Flash) of an Intel
700-series controller through the ixl(4) NVM ioctls, holding a session
across the sequence of admin-queue commands an update requires.

  scan (the default with no arguments)
     inventory every ixl(4) interface -- NVM version, running firmware
     version, EETRACK ID -- group the ports of each card by PCI
     bus/dev, and, against an nvmupdate.cfg, report which cards have an
     upgrade available and the command to apply it.  -q gives a stable
     machine-readable line per card.
  image-apply
     apply an Intel image with a per-module flow: non-authenticated
     outside-shadow modules, the NVM header version words plus a
     recomputed software checksum, then the authenticated modules with
     EMP Image last.  The result matches Intel's own tool for every
     authenticated and non-authenticated module.  An experimental -s
     additionally writes shadow-RAM modules.
  module-update
     update one named module via the same flows.
  image-diff
     module-aware verify: locate each module by the chip's own header
     pointer, read it from the chip, and compare to the image,
     reporting MATCH, DIFFER, MANAGED (chip-populated register/recovery
     state) or PRESERVED (card identity).
  image-show, verify-checksum, match, cfg-read, dump, show
     inspect images, the live checksum, and the manifest.

Writing the NVM requires securelevel 0; see the SECURITY section.

The manual walks through a complete update, from the inventory scan and
Intel's NVM update package to the single-user apply and verification.

For the diff, also see github:
https://github.com/huberste/openbsd-src/tree/ixl-nvm



commit cdba44ec2be3f15824677b3bbb7f6ea485c02026
Author: Stefan Huber <stefan.huber@stusta.de>
Date:   Sun Jul 5 17:05:22 2026 +0200

    ixlnvm(8): manage the NVM of Intel 700-series Ethernet controllers

diff --git usr.sbin/Makefile usr.sbin/Makefile
index da809ac42d7..d4acb9c5e72 100644
--- usr.sbin/Makefile
+++ usr.sbin/Makefile
@@ -8,7 +8,7 @@ SUBDIR=	ac accton acme-client acpidump adduser amd apm
apmd arp authpf \
 	dhcrelay6 dvmrpctl dvmrpd \
 	edquota eeprom eigrpd eigrpctl fdformat ftp-proxy fw_update
gpioctl \
 	hostapd hostctl hotplugd httpd identd ifstated ikectl inetd \
-	installboot iostat iscsictl iscsid kgmon kvm_mkdb ldapd
ldapctl \
+	installboot iostat iscsictl iscsid ixlnvm kgmon kvm_mkdb ldapd
ldapctl \
 	ldomctl ldomd ldpd ldpctl lldp lldpd lpr \
 	makefs mailwrapper map-mbone memconfig \
 	mksuncd mkuboot mopd mrinfo mrouted mtrace mtree ndp
netgroup_mkdb \
diff --git usr.sbin/ixlnvm/Makefile usr.sbin/ixlnvm/Makefile
new file mode 100644
index 00000000000..99eca30fe64
--- /dev/null
+++ usr.sbin/ixlnvm/Makefile
@@ -0,0 +1,6 @@
+#	$OpenBSD$
+
+PROG=	ixlnvm
+MAN=	ixlnvm.8
+
+.include <bsd.prog.mk>
diff --git usr.sbin/ixlnvm/ixlnvm.8 usr.sbin/ixlnvm/ixlnvm.8
new file mode 100644
index 00000000000..40a7e38fb9c
--- /dev/null
+++ usr.sbin/ixlnvm/ixlnvm.8
@@ -0,0 +1,675 @@
+.\"	$OpenBSD$
+.\"
+.\" Copyright (c) 2026 Stefan Huber <stefan.huber@stusta.de>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for
any
+.\" purpose with or without fee is hereby granted, provided that the
above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL THE AUTHOR BE
LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt IXLNVM 8
+.Os
+.Sh NAME
+.Nm ixlnvm
+.Nd manage the NVM of Intel 700-series Ethernet controllers
+.Sh SYNOPSIS
+.Nm ixlnvm
+.Op Cm scan Oo Fl q Oc Oo Fl c Ar nvmupdate.cfg Oc
+.Nm ixlnvm
+.Fl i Ar ifname
+.Cm dump
+.Op Fl o Ar file
+.Nm ixlnvm
+.Fl i Ar ifname
+.Cm show
+.Nm ixlnvm
+.Fl i Ar ifname
+.Cm cfg-read Ar feature_id
+.Nm ixlnvm
+.Fl i Ar ifname
+.Cm selftest
+.Op Fl y
+.Nm ixlnvm
+.Fl i Ar ifname
+.Cm image-diff Ar file
+.Nm ixlnvm
+.Cm image-show Ar file
+.Nm ixlnvm
+.Op Fl i Ar ifname
+.Cm match
+.Fl c Ar nvmupdate.cfg
+.Op Fl e Ar eepid
+.Nm ixlnvm
+.Fl i Ar ifname
+.Cm verify-checksum
+.Nm ixlnvm
+.Fl i Ar ifname
+.Cm image-apply
+.Fl f Ar file
+.Op Fl s
+.Op Fl y
+.Nm ixlnvm
+.Fl i Ar ifname
+.Cm module-update
+.Fl m Ar module
+.Fl f Ar file
+.Op Fl y
+.Sh DESCRIPTION
+.Nm
+reads and updates the non-volatile memory
+.Pq Dq NVM ,
+also referred to as Flash, of an Intel 700-series Ethernet controller
+attached via the
+.Xr ixl 4
+driver.
+It uses the kernel's NVM session ioctls to hold ownership of the
+NVM resource across multiple admin-queue commands.
+.Pp
+The interface to operate on is selected with
+.Fl i Ar ifname .
+.Pp
+The available commands are:
+.Bl -tag -width Ds
+.It Xo
+.Op Cm scan Oo Fl q Oc Oo Fl c Ar nvmupdate.cfg Oc
+.Xc
+List every
+.Xr ixl 4
+interface with its NVM version, running firmware version and
+EETRACK ID, grouping the ports of each physical card by PCI bus and
+device.
+This is the default if no command is given, and it does not take
+.Fl i .
+The
+.Fl q
+and
+.Fl c
+options require the
+.Cm scan
+command to be given explicitly.
+.Pp
+If an
+.Pa nvmupdate.cfg
+manifest is found in the current directory, or one is given with
+.Fl c ,
+each card is matched against it and reported as one of
+.Cm CURRENT ,
+.Cm UPGRADE ,
+.Cm NO_MATCH ,
+.Cm MISSING_BIN
+or
+.Cm ERROR ;
+without a manifest the status is
+.Cm NO_CFG .
+For a card that can be upgraded, the image, the reset type it requires
+.Pq Cm REBOOT No or Cm POWER
+and the exact
+.Cm image-apply
+command line are printed.
+.Pp
+With
+.Fl q ,
+one line per card is printed in a stable, machine-readable format:
+ports, NVM version, firmware version, EETRACK ID, status, image and
+reset type.
+.It Cm dump Op Fl o Ar file
+Read the entire 64 KB NVM as raw bytes.
+With
+.Fl o Ar file ,
+the contents are written to
+.Ar file ;
+otherwise to standard output.
+Writing the binary blob to a terminal is refused; redirect or use
+.Fl o .
+.It Cm show
+Read the NVM header and print a summary of the well-known module
+pointers and the software checksum word.
+.It Cm cfg-read Ar feature_id
+Issue an NVM Config Read admin command (datasheet 3.4.10.4) for the
+given 16-bit
+.Ar feature_id
+and print the 6-byte response.
+For example,
+.Ar feature_id
+0xFFF1 reads the current link-mode selection (1x40G, 2x40G, or 4x10G;
+see datasheet 3.4.5.7).
+This command waits for the asynchronous completion event posted on
+the chip's admin receive queue.
+.It Cm selftest Op Fl y
+Read NVM word 0x16 (the PBA Block pointer, an RW header word per
+datasheet 3.4.5.3) and write the same value back via NVM_UPDATE with
+the Last_Command bit set, exercising the asynchronous bank-swap and
+the kernel's ARQ completion-event demultiplex.
+The card performs a bank swap on Flash, but the NVM contents are
+semantically unchanged (identical-value write keeps the software
+checksum valid).
+Read back and compare to confirm.
+.Pp
+Without
+.Fl y ,
+prints what would happen and exits.
+Pass
+.Fl y
+to confirm and run the test.
+.It Cm image-show Ar file
+Parse an Intel NVM update image
+.Pq Ar file
+and print its NVM control word, software checksum, PBA number,
+and the table of module pointers (with the update flow each module
+needs).
+This subcommand operates on a file and does not require
+.Fl i .
+.It Cm image-diff Ar file
+Verify the chip against an Intel NVM image
+.Pq Ar file ,
+module by module.
+For each NVM module the tool understands, the module is located via
+the
+.Em chip's
+own header pointer
+.Pq not the image's, since a per-module update relocates modules and
swaps banks ,
+its bytes are read from the chip, and they are compared to the image's
+copy of that module.
+Each module is reported as one of:
+.Bl -tag -width PRESERVED -compact
+.It Cm MATCH
+chip content equals the image.
+.It Cm DIFFER
+chip content differs; for a module the image carries, this means the
+module is not yet updated on the chip.
+.It Cm MANAGED
+a chip-populated register auto-load or data-recovery module
+.Pq e.g. Cm GLOBR Auto-load , Cm SW-Data-Recovery :
+it differs from the static image by design
+.Pq the firmware fills it with computed/runtime state
+and is excluded from the pass/fail tally.
+.It Cm PRESERVED
+a card-identity field
+.Pq MAC, VPD, PBA, PXE, VLAN, boot config
+that an apply deliberately leaves untouched.
+.It Cm ABSENT No / Cm SKIP
+the module is not present in the image, or its size cannot be
+determined.
+.El
+.Pp
+A correctly updated card reports every authenticated and
+non-authenticated module as
+.Cm MATCH
+and zero
+.Cm DIFFER ;
+the
+.Cm MANAGED
+modules differ identically to how Intel's own tool leaves them.
+This is the recommended way to confirm an
+.Cm image-apply
+took effect.
+.It Xo
+.Cm match
+.Fl c Ar nvmupdate.cfg
+.Op Fl e Ar eepid
+.Xc
+Parse Intel's
+.Ar nvmupdate.cfg
+manifest and identify which packaged
+.Pa .bin
+image is appropriate for a given EETRACK ID.
+Without
+.Fl e ,
+.Fl i Ar ifname
+must be given and the chip's current EETRACK ID is read from words
+0x2d-0x2e of its NVM.
+With
+.Fl e ,
+the EETRACK ID is taken from the command line as a hex string.
+.Pp
+The result names the matching
+.Cm NVM IMAGE
+file, its target EEPID, the required reset type
+.Pq POWER No or Cm REBOOT ,
+and whether the chip is already at the matched image or needs to
+upgrade to it (via the cfg's
+.Cm REPLACES
+list).
+.It Cm verify-checksum
+Read the chip's shadow RAM and verify the software checksum at
+word 0x3f against the value an independent computation derives
+from the same bytes (datasheet 6.1.4.1).
+A match confirms that the chip's NVM state is internally consistent
+and that this tool's checksum algorithm agrees with the firmware's.
+.It Xo
+.Cm image-apply
+.Fl f Ar file
+.Op Fl s
+.Op Fl y
+.Xc
+Apply an Intel NVM image to the chip by running the per-module update
+flow for each module in turn, in three phases:
+.Bl -enum -compact
+.It
+Phase 1: the non-authenticated outside-shadow modules
+.Pq datasheet 3.4.5.4 :
+.Cm EMP Global ,
+.Cm Manageability ,
+.Cm EMP Settings ,
+.Cm PHY Config Scripts ,
+.Cm Configuration Metadata ,
+and
+.Cm External 25G PHY .
+.It
+Phase 2 (only with
+.Fl s ,
+.Sy experimental ) :
+the read/write shadow-RAM modules
+.Pq datasheet 3.4.5.3 .
+This is not part of the supported upgrade: the chip's EMP regenerates
+most of these modules on its own, and direct shadow writes have proven
+fragile and chip-state-dependent.
+See
+.Sx CAVEATS .
+.It
+Phase 2b: the NVM header version words
+.Pq Cm DEV_STARTER_VERSION No word 0x18, Cm EETRACK ID No words 0x2d-
0x2e
+and the recomputed software checksum, so the chip reports the new
+image version after the upgrade.
+.It
+Phase 3: the authenticated outside-shadow modules
+.Pq datasheet 3.4.5.5 :
+.Cm PCIe Analog ,
+.Cm PHY Analog ,
+.Cm Option ROM ,
+and
+.Cm EMP Image .
+.El
+.Pp
+.Cm EMP Image
+is applied last: after its
+.Cm LAST_COMMAND
+the chip stops servicing admin-queue commands until power-
cycle/reboot,
+so it must be the final step.
+Each authenticated module's RSA-2048 signature is verified by the chip
+on
+.Cm LAST_COMMAND
+and a mismatch causes the chip to reject that module
+.Pq the previous one stays active .
+Modules absent from the image
+.Pq pointer 0xffff/0x0000
+are skipped.
+.Pp
+Without
+.Fl y ,
+.Cm image-apply
+is a dry run: validates the image checksum, EETRACK ID, and per-module
+source offsets, and prints the per-module plan.
+With
+.Fl y ,
+the chip is actually written.
+A reboot is required afterwards.
+.It Xo
+.Cm module-update
+.Fl m Ar module
+.Fl f Ar file
+.Op Fl y
+.Xc
+Update a single NVM module from an Intel NVM image, using the same
+per-module update flow as
+.Cm image-apply .
+The module is selected by name with
+.Fl m .
+.Pp
+Authenticated outside-shadow modules
+.Pq datasheet 3.4.5.5 ,
+whose RSA-2048 signature the chip verifies on
+.Cm LAST_COMMAND
+before switching to them; if verification fails, the update is
+rejected and the old module stays active:
+.Bl -tag -width "globr-autoload" -compact
+.It Cm option-rom
+Option ROM: PXE and UEFI network boot code (1160\~KB).
+.It Cm emp-image
+EMP Image: the firmware of the embedded management processor
+(EMP) that runs the controller (1160\~KB).
+After it is written the chip stops servicing admin-queue commands
+until the system is rebooted; see
+.Sx CAVEATS .
+.It Cm pcie-analog
+PCIe Analog: PCIe SerDes analog settings (8\~KB).
+.It Cm phy-analog
+PHY Analog: Ethernet PHY analog settings (8\~KB).
+.El
+.Pp
+Non-authenticated outside-shadow modules
+.Pq datasheet 3.4.5.4 ,
+written without a signature check:
+.Bl -tag -width "globr-autoload" -compact
+.It Cm emp-global
+EMP Global: global settings of the EMP firmware (8\~KB).
+.It Cm manageability
+Manageability: configuration of the sideband manageability
+interfaces, such as NC-SI (8\~KB).
+.It Cm emp-settings
+EMP Settings: further EMP firmware settings (8\~KB).
+.It Cm phy-scripts
+PHY Config Scripts: link and PHY configuration scripts run by the
+firmware (8\~KB).
+.It Cm config-meta
+Configuration Metadata: the description of the configurable NVM
+options (128\~KB).
+.It Cm ext-25g-phy
+External 25G PHY: firmware for an external 25G PHY, present only on
+cards that have one (128\~KB).
+.El
+.Pp
+An outside-shadow module is written sector by sector with
+interleaved
+.Cm NVM_Erase
+and
+.Cm NVM_Update
+admin-queue commands, the final command carrying
+.Cm LAST_COMMAND .
+.Pp
+Shadow-RAM modules
+.Pq datasheet 3.4.5.3
+live inside the 64 KB shadow RAM and are written with
+.Cm NVM_Update
+followed by a recomputed software checksum.
+Writing them is
+.Sy experimental ;
+see
+.Sx CAVEATS .
+The NVM header word holding each module's pointer is given in
+parentheses:
+.Bl -tag -width "globr-autoload" -compact
+.It Cm auto-gen-ptrs
+Auto Generated Pointers (0x07).
+.It Cm pcir-autoload
+Registers loaded on PCIe reset (0x08).
+.It Cm por-autoload
+Registers loaded on power-on reset (0x38).
+.It Cm globr-autoload
+Registers loaded on global reset (0x3b).
+.It Cm corer-autoload
+Registers loaded on core reset (0x3c).
+.It Cm emp-sr
+EMP shadow-RAM settings (0x48).
+.It Cm feature-cfg
+Feature Configuration (0x49).
+.It Cm core-mem
+Core memory configuration (0x4a).
+.It Cm immediate
+Immediate Fields (0x4e).
+.El
+.Pp
+Card-identity data
+.Pq PBA, boot configuration, SAN MAC, VPD, PXE and VLAN settings
+is never written.
+.Pp
+Without
+.Fl y ,
+prints the plan and exits.
+With
+.Fl y ,
+the chip is actually written.
+A reboot is required afterwards.
+.El
+.Sh SECURITY
+Reading the NVM
+.Pq Cm dump , show , scan , image-diff , verify-checksum , No etc.
+is permitted at any
+.Xr securelevel 7 .
+Writing the NVM
+.Pq Cm image-apply , module-update No with Fl y
+opens a write session, which the kernel allows only at securelevel 0
+or below.
+In the default multi-user securelevel
+.Pq 1 ,
+with the network up, opening a write session fails with
+.Er EPERM .
+This prevents a privileged remote attacker from flashing malicious
+firmware on a running, network-reachable system: to update firmware,
+boot into single-user mode
+.Pq which is administered from the local console and starts no network
services ,
+apply the image, and reboot.
+The complete procedure is shown in
+.Sx EXAMPLES .
+.Sh EXIT STATUS
+.Ex -std ixlnvm
+.Sh EXAMPLES
+The following shows a complete NVM update of a system with two
+X710-DA2 cards.
+.Pp
+First, list the cards and their current NVM and firmware versions:
+.Bd -literal -offset indent
+# ixlnvm
+scanning ixl(4) interfaces; nvmupdate.cfg not found, inventory only
+
+ixl0,ixl1  (pci 5:0, 2 ports)
+           nvm 9.30  fw 9.130.73618  eetrack 0x8000e5d7  NO_CFG
+ixl2,ixl3  (pci 7:0, 2 ports)
+           nvm 9.20  fw 9.120.73026  eetrack 0x8000d87f  NO_CFG
+
+summary: 0 upgrade, 0 current, 0 no-match, 0 missing-bin, 0 error
+.Ed
+.Pp
+Download the
+.Dq NVM Update Utility for Intel Ethernet Network Adapter 700 Series
+from Intel.
+This link always leads to the latest version:
+.Pp
+.Lk https://www.intel.com/content/www/us/en/download/18190/
+.Pp
+Intel requires accepting a license in a web browser before the
+download starts, so the package cannot be fetched with
+.Xr ftp 1 .
+The download is a ZIP archive containing one package per operating
+system.
+.Nm
+uses only the
+.Pa nvmupdate.cfg
+manifest and the
+.Pa .bin
+images from the Linux package, not Intel's update tool.
+Extract the Linux package, for example with
+.Ic unzip
+from packages, and unpack it:
+.Bd -literal -offset indent
+# unzip 700Series_NVMUpdatePackage_v9_58.zip \e
+    700Series_NVMUpdatePackage_v9_58_Linux.tar.gz
+# tar -xzf 700Series_NVMUpdatePackage_v9_58_Linux.tar.gz
+.Ed
+.Pp
+Run
+.Nm
+again from the directory containing the manifest
+.Pq or pass it with Fl c
+to see which cards can be upgraded, and the command to do so:
+.Bd -literal -offset indent
+# cd 700Series/Linux_x64
+# ixlnvm
+scanning ixl(4) interfaces against nvmupdate.cfg (120 entries)
+
+ixl0,ixl1  (pci 5:0, 2 ports)
+           nvm 9.30  fw 9.130.73618  eetrack 0x8000e5d7  UPGRADE
+           upgrade to X710DA2_9p58_CFGID7p2_OEMGEN.bin (reset REBOOT)
+           apply:  ixlnvm -i ixl0 image-apply -f
X710DA2_9p58_CFGID7p2_OEMGEN.bin -y
+ixl2,ixl3  (pci 7:0, 2 ports)
+           nvm 9.20  fw 9.120.73026  eetrack 0x8000d87f  UPGRADE
+           upgrade to X710DA2_9p58_CFGID7p2_OEMGEN.bin (reset REBOOT)
+           apply:  ixlnvm -i ixl2 image-apply -f
X710DA2_9p58_CFGID7p2_OEMGEN.bin -y
+
+summary: 2 upgrade, 0 current, 0 no-match, 0 missing-bin, 0 error
+.Ed
+.Pp
+Writing the NVM requires
+.Xr securelevel 7
+0
+.Pq see Sx SECURITY .
+Reboot and, at the
+.Xr boot 8
+prompt, boot into single-user mode, which runs at securelevel 0:
+.Bd -literal -offset indent
+boot> boot -s
+.Ed
+.Pp
+In single-user mode only the root file system is mounted, read-only.
+Mount the other file systems so that
+.Pa /usr/sbin/ixlnvm
+and the unpacked package are available
+.Pq run Xr fsck 8 No first if Xr mount 8 No refuses ,
+and confirm the securelevel:
+.Bd -literal -offset indent
+# mount -a
+# sysctl kern.securelevel
+kern.securelevel=0
+.Ed
+.Pp
+Change to the package directory again and run the
+.Dq apply:
+line printed for each card.
+Only one port per card needs to be given.
+A complete run looks like this:
+.Bd -literal -offset indent
+# cd 700Series/Linux_x64
+# ixlnvm -i ixl2 image-apply -f X710DA2_9p58_CFGID7p2_OEMGEN.bin -y
+image:      X710DA2_9p58_CFGID7p2_OEMGEN.bin
+  size:       4194304 bytes
+  firmware:   9.58
+  EETRACK ID: 0x800104df
+  checksum:   0xea10 [ok]
+chip:       ixl2
+  EETRACK ID: 0x8000d87f (different)
+
+plan: per-module update across three phases
+
+  Phase 1: FLOW_NONAUTH (datasheet 3.4.5.4)
+    EMP Global            src 0x026000     2 sectors (update 0x09,
erase 0x46)
+    Manageability         src 0x028000     2 sectors (update 0x0e,
erase 0x46)
+    EMP Settings          src 0x02a000     2 sectors (update 0x0f,
erase 0x46)
+    PHY Config Scripts    src 0x024000     2 sectors (update 0x3d,
erase 0x46)
+    Configuration Meta    src 0x3b4000    32 sectors (update 0x4d,
erase 0x44)
+    External 25G PHY      (not in image, skipped)
+
+  Phase 2: FLOW_SHADOW (datasheet 3.4.5.3, batched) [EXPERIMENTAL]
+    DISABLED (default).  -s enables it, but the EMP
+    regenerates these modules and direct writes are
+    fragile; the supported flow does not use -s.
+
+  Phase 2b: NVM header version words (always on)
+    word 0x18 (DEV_STARTER_VERSION) <- image
+    words 0x2d/0x2e (EETRACK ID)    <- image
+    word 0x3f (software checksum)   <- recomputed [LAST]
+
+  Phase 3: FLOW_AUTH (datasheet 3.4.5.5)
+    PCIe Analog           src 0x020000     2 sectors (update 0x03,
erase 0x46)
+    PHY Analog            src 0x022000     2 sectors (update 0x04,
erase 0x46)
+    Option ROM            src 0x02e000   290 sectors (update 0x05,
erase 0x40)
+    EMP Image             src 0x150000   290 sectors (update 0x0b,
erase 0x40)  <- EMP last
+
+  FLOW_AUTH modules: chip verifies RSA-2048 signature on
+    LAST_COMMAND; mismatch keeps the old module active.
+  FLOW_NONAUTH/FLOW_SHADOW: written without signature check.
+  reboot required after completion.
+
+*** writing chip NVM.  DO NOT INTERRUPT.
+  EMP Global: sector    2/2  write [LAST]
+  Manageability: sector    2/2  write [LAST]
+  EMP Settings: sector    2/2  write [LAST]
+  PHY Config Scripts: sector    2/2  write [LAST]
+  Configuration Meta: sector   32/32  write [LAST]
+  reading shadow: 64 / 64 KB
+
+  header: nvm version 0x9058 (word 0x18)
+  header: EETRACK 0x800104df (words 0x2d/0x2e)
+  header: checksum 0xbdce at word 0x3f [LAST]
+  PCIe Analog: sector    2/2  write [LAST]
+  PHY Analog: sector    2/2  write [LAST]
+  Option ROM: sector  290/290  write [LAST]
+  EMP Image: sector  290/290  write [LAST]
+
+Image apply completed.  Reboot the system to load the new firmware.
+# ixlnvm -i ixl0 image-apply -f X710DA2_9p58_CFGID7p2_OEMGEN.bin -y
+\&...
+.Ed
+.Pp
+Do not interrupt the update or remove power while it runs.
+Leaving out
+.Fl y
+prints the plan without writing anything.
+.Pp
+Once all cards are written, reboot
+.Pq or, for a card whose reset type is Cm POWER , power the system off
and on again :
+.Bd -literal -offset indent
+# reboot
+.Ed
+.Pp
+After the reboot, running
+.Nm
+in the package directory reports each updated card as
+.Cm CURRENT .
+To compare a card with the image module by module:
+.Bd -literal -offset indent
+# ixlnvm -i ixl2 image-diff X710DA2_9p58_CFGID7p2_OEMGEN.bin
+.Ed
+.Pp
+Dump the NVM of
+.Li ixl0
+to a file:
+.Bd -literal -offset indent
+# ixlnvm -i ixl0 dump -o ixl0.nvm
+.Ed
+.Pp
+Display the NVM header summary:
+.Bd -literal -offset indent
+# ixlnvm -i ixl0 show
+.Ed
+.Sh SEE ALSO
+.Xr ixl 4 ,
+.Xr ifconfig 8
+.Sh HISTORY
+The
+.Nm
+utility first appeared in
+.Ox 8.1 .
+.Sh AUTHORS
+.An Stefan Huber Aq Mt stefan.huber@stusta.de
+.Sh CAVEATS
+Only one process at a time can hold an NVM session on an interface;
+while one is open, a second
+.Nm
+on the same interface fails with
+.Er EBUSY .
+.Pp
+After
+.Cm image-apply
+or
+.Cm module-update Fl m Cm emp-image ,
+the chip stops servicing admin-queue commands and stays in that
+state until power-cycle or reboot.
+This is normal: the running EMP firmware was just replaced and is
+waiting to be reloaded.
+.Pp
+The shadow-RAM update phase
+.Pq Cm image-apply Fl s , No or Cm module-update No of a shadow-RAM
module
+is
+.Sy experimental
+and not part of the supported upgrade flow.
+The chip's EMP firmware regenerates most shadow-RAM modules on its
own,
+so a normal
+.Cm image-apply
+.Pq without Fl s
+already produces a complete, version-consistent upgrade; this can be
+confirmed with
+.Cm image-diff ,
+which compares each module on the chip against the image.
+Direct shadow-RAM writes have proven fragile and chip-state-dependent
+(intermittent
+.Er EIO )
+and several shadow-RAM modules are read-only or firmware-managed and
+reject writes outright.
diff --git usr.sbin/ixlnvm/ixlnvm.c usr.sbin/ixlnvm/ixlnvm.c
new file mode 100644
index 00000000000..cfb5c2824e9
--- /dev/null
+++ usr.sbin/ixlnvm/ixlnvm.c
@@ -0,0 +1,2927 @@
+/*	$OpenBSD$ */
+
+/*
+ * Copyright (c) 2026 Stefan Huber <stefan.huber@stusta.de>
+ *
+ * Permission to use, copy, modify, and distribute this software for
any
+ * purpose with or without fee is hereby granted, provided that the
above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL THE AUTHOR BE
LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+/*
+ * ixlnvm - manage the NVM (Flash) of Intel 700-series controllers via
ixl(4).
+ *
+ * Uses SIOCSIFNVMOPEN / SIOCSIFNVMCMD / SIOCSIFNVMCLOSE to hold an
NVM
+ * session across a sequence of admin-queue commands.
+ */
+
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <sys/sockio.h>
+#include <sys/ioctl.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+
+#include <net/if.h>
+
+#include <ctype.h>
+#include <err.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <ifaddrs.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+#ifndef nitems
+#define nitems(_a)	(sizeof((_a)) / sizeof((_a)[0]))
+#endif
+
+/*
+ * AQ opcodes and NVM command flags (datasheet sections 3.4.10.x).
+ * Mirrored from sys/dev/pci/if_ixl.c; the chip ABI is stable.
+ */
+#define IXL_AQ_OP_NVM_READ		0x0701
+#define IXL_AQ_OP_NVM_ERASE		0x0702
+#define IXL_AQ_OP_NVM_UPDATE		0x0703
+#define IXL_AQ_OP_NVM_CFG_READ		0x0704
+
+/*
+ * NVM_UPDATE command_flags byte (byte 16 of the AQ descriptor).
+ * Datasheet 3.4.10.3 documents bit 0 (LAST_COMMAND) and bit 7
+ * (FLASH_ONLY) and marks bits 6:1 as "reserved".  In practice
+ * (datasheet 3.4.5.6 prose, and Intel's i40e Linux driver
+ * adminq_cmd.h) the chip recognises additional bits:
+ */
+#define IXL_AQ_NVM_LAST_COMMAND		(1 << 0)
+#define IXL_AQ_NVM_PRESERVE_ALL		(1 << 1)
+#define IXL_AQ_NVM_PRESERVE_SELECTED	(3 << 1)
+#define IXL_AQ_NVM_REARRANGE_TO_FLAT	(1 << 5)
+#define IXL_AQ_NVM_REARRANGE_TO_STRUCT	(1 << 6)
+#define IXL_AQ_NVM_FLASH_ONLY		(1 << 7)
+
+/* NVM Image module pointer, used by the flat update flow (3.4.5.6).
*/
+#define IXL_NVM_MODULE_FLAT_IMAGE	0x42
+
+#define IXL_NVM_CHUNK			IFNVM_CMD_MAX_BUFLEN
+
+/* NVM_CFG_READ response buffer per datasheet 3.4.10.7 (6 bytes per
element). */
+#define IXL_NVM_CFG_ELEMENT_SIZE	6
+
+/* Selected NVM header word offsets (datasheet 6.1.2 / 6.3 / table 6-
2). */
+#define NVM_W_CONTROL1			0x00
+#define NVM_W_PCIE_ANALOG		0x03
+#define NVM_W_PHY_ANALOG		0x04
+#define NVM_W_OPTION_ROM		0x05
+#define NVM_W_EMP_GLOBAL		0x09
+#define NVM_W_EMP_IMAGE			0x0b
+#define NVM_W_MANAGEABILITY		0x0e
+#define NVM_W_EMP_SETTINGS		0x0f
+#define NVM_W_PBA_BLOCK			0x16
+#define NVM_W_BOOT_CONFIG		0x17
+#define NVM_W_DEV_STARTER_VERSION	0x18	/* high=major,
low=minor */
+#define NVM_W_PERM_SAN_MAC		0x28
+#define NVM_W_EETRACK_LO		0x2d
+#define NVM_W_EETRACK_HI		0x2e
+#define NVM_W_VPD			0x2f
+#define NVM_W_PHY_SCRIPTS		0x3d
+#define NVM_W_PCIE_ALT			0x3e
+#define NVM_W_SW_CHECKSUM		0x3f
+#define NVM_W_CONFIG_META		0x4d
+#define NVM_W_EXT_25G_PHY		0x4f
+
+/*
+ * Sub-module offsets within the Boot Config Block (pointed to by word
+ * 0x17).  The OEM version is two words starting at word 0x83.  This
+ * specific offset isn't in the public datasheet section we have but
is
+ * documented in Intel's open-source i40e driver (i40e_type.h).
+ */
+#define BOOT_CFG_OEM_VER_OFFSET		0x83
+
+/* Software checksum coverage (datasheet 6.1.4.1). */
+#define NVM_SR_SIZE_WORDS		(64 * 1024 / 2)
+#define NVM_SR_CHECKSUM_BASE		0xBABA
+/*
+ * Sizes used by the checksum-skipping logic.  Per datasheet table
+ * 6-2: VPD area has max provisioned size 1024 bytes (512 words);
+ * PCIe ALT Auto-load has max size 1024 bytes (512 words).  The
+ * checksum routine skips the maximum range so it works regardless
+ * of the module's actual size.
+ */
+#define NVM_CHECKSUM_VPD_SKIP_WORDS	512
+#define NVM_CHECKSUM_PCIE_ALT_SKIP_WORDS 512
+
+static __dead void	usage(void);
+static int		cmd_dump(int, const char *, int, char **);
+static int		cmd_show(int, const char *, int, char **);
+static int		cmd_cfg_read(int, const char *, int, char **);
+static int		cmd_selftest(int, const char *, int, char **);
+static int		cmd_image_show(int, const char *, int, char
**);
+static int		cmd_image_diff(int, const char *, int, char
**);
+static int		cmd_match(int, const char *, int, char **);
+static int		cmd_verify_checksum(int, const char *, int,
char **);
+static int		cmd_image_apply(int, const char *, int, char
**);
+static int		cmd_module_update(int, const char *, int, char
**);
+static int		cmd_scan(int, char **);
+
+static void		nvm_open(int, const char *, uint8_t);
+static void		nvm_close(int, const char *);
+static void		nvm_read(int, const char *, uint32_t,
uint16_t,
+			    void *, int);
+static void		nvm_read_full(int, const char *, uint32_t,
size_t,
+			    void *, const char *);
+static int		nvm_erase_chunk(int, const char *, uint8_t,
+			    uint32_t, uint16_t, uint8_t, int,
uint16_t);
+
+/*
+ * Per datasheet 3.4.10.2 the NVM_Erase command's module_pointer
+ * field must be the word address of a FREE PROVISIONING AREA
+ * pointer, not the target module's pointer; using the target
+ * module's pointer gets EPERM from the chip.  NVM_Update uses the
+ * target module's pointer (3.4.5.4 / 3.4.5.5 step 2).
+ *
+ * FLOW_AUTH (3.4.5.5, RSA-signed):
+ *   Option ROM, EMP Image          -> erase via 0x40 (1st free, 1160
KB)
+ *   PCIe Analog, PHY Analog        -> erase via 0x46 (2nd free, 8 KB)
+ *
+ * FLOW_NONAUTH (3.4.5.4, no signature):
+ *   EMP Global, Manageability,
+ *   EMP Settings, PHY Cfg Scripts  -> erase via 0x46 (2nd free, 8 KB)
+ *   Config Metadata,
+ *   External 25G PHY Global        -> erase via 0x44 (3rd free, 128
KB)
+ *
+ * Modules share a free area sequentially (one update at a time);
+ * the per-module max-size is the free area's capacity since each
+ * module image in the source NVM is padded to that size.
+ */
+struct module_info {
+	const char	*cli_name;
+	const char	*display_name;
+	uint16_t	 update_ptr_word;	/* NVM_Update
module_pointer */
+	uint16_t	 erase_ptr_word;	/* NVM_Erase 
module_pointer */
+	uint32_t	 max_size_bytes;
+};
+
+/*
+ * EXPERIMENTAL.  Shadow-RAM modules (FLOW_SHADOW, datasheet 3.4.5.3).
+ * Only reached via image-apply -s, which is not the supported upgrade
+ * path: the chip's EMP regenerates most of these modules on its own
+ * (verified -- a no-`-s` upgrade leaves POR/CORER/RO-PCIe-LCB/etc.
+ * already matching the image), and direct shadow writes have proven
+ * fragile and chip-state-dependent (intermittent EIO mid-batch).  The
+ * production flow is Phase 1 (FLOW_NONAUTH) + header version + Phase
3
+ * (FLOW_AUTH).  Kept for completeness / experimentation only.
+ *
+ * These live
+ * inside the 64 KB shadow RAM; their pointer-word value (bit 15
clear)
+ * is interpreted in word units within shadow RAM (byte_offset =
+ * value * 2).  The module's first word holds its length in words,
+ * exclusive of the length word itself (datasheet 6.1.5.1 / Table 6-
4).
+ *
+ * Only firmware-dependent RW modules appear here.  The PFA list (PBA
+ * 0x16, Boot Config 0x17, SAN MAC 0x28, VPD 0x2f, PXE 0x30/0x31, VLAN
+ * 0x37) is preserved by NOT including those words.
+ *
+ * Writes use NVM_Update with module_pointer = 0; no NVM_Erase is
+ * needed (the chip stages writes in the inactive bank and commits on
+ * LAST_COMMAND).  Software must recompute word 0x3f checksum.
+ */
+struct shadow_module_info {
+	const char	*cli_name;
+	const char	*display_name;
+	uint16_t	 pointer_word;
+};
+
+static const struct shadow_module_info shadow_module_table[] = {
+	{ "auto-gen-ptrs", "Auto Generated Pointers", 0x07 },
+	{ "pcir-autoload", "PCIR Auto-load",          0x08 },
+	{ "por-autoload",  "POR Auto-load",           0x38 },
+	{ "globr-autoload","GLOBR Auto-load",         0x3b },
+	{ "corer-autoload","CORER Auto-load",         0x3c },
+	{ "emp-sr",        "EMP SR Settings",         0x48 },
+	{ "feature-cfg",   "Feature Configuration",   0x49 },
+	{ "core-mem",      "Core Mem Config",         0x4a },
+	{ "immediate",     "Immediate Fields",        0x4e },
+	/*
+	 * The *_Registers Auto-load modules (0x08, 0x38, 0x3b, 0x3c)
are
+	 * RW, length-prefixed (datasheet 6.1.5.1 Table 6-4), and
mapped
+	 * IN shadow RAM (Table 6-2: pointer type 0b = word units). 
They
+	 * are large (CORER ~43 KB) and frequently begin mid-page, so
they
+	 * must be written with write_shadow_region()'s page-boundary
+	 * clipping (see its comment) or the chip returns EINVAL.
+	 *
+	 * Excluded by design (all RO per Table 6-2, datasheet
6.3.1.x):
+	 *   RO PCIR Auto-load (0x06), RO PCIe LCB (0x0a), Reserved
EMPR
+	 *     Auto-load (0x3a), PCIe ALT Auto-load (0x3e),
+	 *     SW-Data-Recovery (0x59), Preservation Rules (0x70).
+	 *   PCIR-Data-Recovery (0x5a) -- RO per datasheet 6.3.1.78;
+	 *     firmware-managed runtime recovery state (validity bits
the
+	 *     EMP sets), not image content.  The chip rejects direct
+	 *     shadow writes to it (EPERM, AQ retval 0x0001).
+	 *   0x0a likewise rejects direct writes (EPERM); the EMP
+	 *     regenerates it from other modules.
+	 */
+};
+
+static const struct module_info module_table[] = {
+	/* FLOW_AUTH (3.4.5.5) */
+	{ "option-rom",  "Option ROM",  NVM_W_OPTION_ROM,  0x40, 1160
* 1024 },
+	{ "emp-image",   "EMP Image",   NVM_W_EMP_IMAGE,   0x40, 1160
* 1024 },
+	{ "pcie-analog", "PCIe Analog", NVM_W_PCIE_ANALOG, 0x46,    8
* 1024 },
+	{ "phy-analog",  "PHY Analog",  NVM_W_PHY_ANALOG,  0x46,    8
* 1024 },
+	/* FLOW_NONAUTH (3.4.5.4) */
+	{ "emp-global",   "EMP Global",         NVM_W_EMP_GLOBAL,  
0x46,   8 * 1024 },
+	{ "manageability","Manageability",     
NVM_W_MANAGEABILITY,0x46,   8 * 1024 },
+	{ "emp-settings", "EMP Settings",       NVM_W_EMP_SETTINGS,
0x46,   8 * 1024 },
+	{ "phy-scripts",  "PHY Config Scripts", NVM_W_PHY_SCRIPTS, 
0x46,   8 * 1024 },
+	{ "config-meta",  "Configuration Meta", NVM_W_CONFIG_META, 
0x44, 128 * 1024 },
+	{ "ext-25g-phy",  "External 25G PHY",   NVM_W_EXT_25G_PHY, 
0x44, 128 * 1024 },
+};
+
+static int		apply_module(int, const char *,
+			    const struct module_info *, const uint8_t
*,
+			    uint32_t, uint32_t);
+static int		cmd_shadow_update_single(int, const char *,
+			    const struct shadow_module_info *,
+			    const char *, int);
+struct shadow_step {
+	const struct shadow_module_info *sm;
+	uint32_t	byte_start;
+	uint32_t	byte_len;
+	int		present;
+};
+static size_t		resolve_shadow_batch(const uint8_t *,
+			    struct shadow_step *, size_t);
+static void		apply_shadow_batch(int, const char *, const
uint8_t *,
+			    struct shadow_step *, size_t);
+static void		apply_header_version(int, const char *,
+			    const uint8_t *);
+
+static void
+usage(void)
+{
+	fprintf(stderr,
+	    "usage: ixlnvm [scan [-q] [-c nvmupdate.cfg]]\n"
+	    "       ixlnvm -i ifname dump [-o file]\n"
+	    "       ixlnvm -i ifname show\n"
+	    "       ixlnvm -i ifname cfg-read feature_id\n"
+	    "       ixlnvm -i ifname selftest [-y]\n"
+	    "       ixlnvm -i ifname image-diff file\n"
+	    "       ixlnvm image-show file\n"
+	    "       ixlnvm [-i ifname] match -c nvmupdate.cfg [-e
eepid]\n"
+	    "       ixlnvm -i ifname verify-checksum\n"
+	    "       ixlnvm -i ifname image-apply -f file [-s] [-y]\n"
+	    "       ixlnvm -i ifname module-update -m module -f file
[-y]\n");
+	exit(1);
+}
+
+int
+main(int argc, char *argv[])
+{
+	const char *ifname = NULL;
+	int s, ch;
+
+	while ((ch = getopt(argc, argv, "i:")) != -1) {
+		switch (ch) {
+		case 'i':
+			ifname = optarg;
+			break;
+		default:
+			usage();
+		}
+	}
+	argc -= optind;
+	argv += optind;
+
+	/* No subcommand and no -i: default to scanning the system. */
+	if (argc < 1) {
+		if (ifname != NULL)
+			usage();
+		return (cmd_scan(argc, argv));
+	}
+
+	/* scan: walk all ixl(4) interfaces against ./nvmupdate.cfg */
+	if (strcmp(argv[0], "scan") == 0)
+		return (cmd_scan(argc, argv));
+
+	/* image-* subcommands operate on a file, not a card */
+	if (strcmp(argv[0], "image-show") == 0)
+		return (cmd_image_show(-1, NULL, argc, argv));
+
+	/* match works with or without -i (offline -e mode or live -i
mode) */
+	if (strcmp(argv[0], "match") == 0) {
+		int s2 = -1;
+		if (ifname != NULL) {
+			s2 = socket(AF_INET, SOCK_DGRAM, 0);
+			if (s2 == -1)
+				err(1, "socket");
+		}
+		return (cmd_match(s2, ifname, argc, argv));
+	}
+
+	if (ifname == NULL)
+		usage();
+
+	s = socket(AF_INET, SOCK_DGRAM, 0);
+	if (s == -1)
+		err(1, "socket");
+
+	if (strcmp(argv[0], "dump") == 0)
+		return (cmd_dump(s, ifname, argc, argv));
+	if (strcmp(argv[0], "show") == 0)
+		return (cmd_show(s, ifname, argc, argv));
+	if (strcmp(argv[0], "cfg-read") == 0)
+		return (cmd_cfg_read(s, ifname, argc, argv));
+	if (strcmp(argv[0], "selftest") == 0)
+		return (cmd_selftest(s, ifname, argc, argv));
+	if (strcmp(argv[0], "image-diff") == 0)
+		return (cmd_image_diff(s, ifname, argc, argv));
+	if (strcmp(argv[0], "verify-checksum") == 0)
+		return (cmd_verify_checksum(s, ifname, argc, argv));
+	if (strcmp(argv[0], "image-apply") == 0)
+		return (cmd_image_apply(s, ifname, argc, argv));
+	if (strcmp(argv[0], "module-update") == 0)
+		return (cmd_module_update(s, ifname, argc, argv));
+
+	usage();
+}
+
+/*
+ * Tunnel wrappers around the SIOCSIFNVM* ioctls.
+ *
+ * They err()/errx() on failure rather than returning, since none of
the
+ * subcommands need finer-grained recovery for the minimal feature
set.
+ */
+
+static void
+nvm_open(int s, const char *ifname, uint8_t access)
+{
+	struct if_nvmsess ns;
+
+	memset(&ns, 0, sizeof(ns));
+	if (strlcpy(ns.ns_ifname, ifname, sizeof(ns.ns_ifname)) >=
+	    sizeof(ns.ns_ifname))
+		errx(1, "interface name too long");
+	ns.ns_access = access;
+
+	if (ioctl(s, SIOCSIFNVMOPEN, &ns) == -1) {
+		if (errno == EPERM && access == IFNVM_ACCESS_WRITE) {
+			errx(1, "%s: cannot open NVM write session:
writing "
+			    "firmware requires securelevel <= 0 (boot
single-"
+			    "user, at the local console); reads are
allowed at "
+			    "any securelevel", ifname);
+		}
+		err(1, "%s: open NVM session", ifname);
+	}
+}
+
+static void
+nvm_close(int s, const char *ifname)
+{
+	struct if_nvmsess ns;
+
+	memset(&ns, 0, sizeof(ns));
+	if (strlcpy(ns.ns_ifname, ifname, sizeof(ns.ns_ifname)) >=
+	    sizeof(ns.ns_ifname))
+		errx(1, "interface name too long");
+	ns.ns_access = IFNVM_ACCESS_READ;	/* ignored by close */
+
+	if (ioctl(s, SIOCSIFNVMCLOSE, &ns) == -1)
+		warn("%s: close NVM session", ifname);
+}
+
+static void
+nvm_read(int s, const char *ifname, uint32_t offset, uint16_t length,
+    void *buf, int last)
+{
+	struct if_nvmcmd nc;
+
+	memset(&nc, 0, sizeof(nc));
+	if (strlcpy(nc.nc_ifname, ifname, sizeof(nc.nc_ifname)) >=
+	    sizeof(nc.nc_ifname))
+		errx(1, "interface name too long");
+	nc.nc_opcode = IXL_AQ_OP_NVM_READ;
+	nc.nc_cmdflags = last ? IXL_AQ_NVM_LAST_COMMAND : 0;
+	nc.nc_module = 0;	/* 0 = flat Flash */
+	nc.nc_offset = offset;
+	nc.nc_aqlen = length;	/* bytes to read */
+	nc.nc_buflen = length;	/* same buffer size */
+	nc.nc_buf = buf;
+
+	if (ioctl(s, SIOCSIFNVMCMD, &nc) == -1)
+		err(1, "%s: NVM read offset 0x%x length %u",
+		    ifname, offset, length);
+	if (nc.nc_aqlen != length)
+		warnx("%s: short NVM read at 0x%x: requested %u, got
%u",
+		    ifname, offset, length, nc.nc_aqlen);
+}
+
+static int
+cmd_dump(int s, const char *ifname, int argc, char **argv)
+{
+	const size_t total = IFNVM_MAX_WORDS * sizeof(uint16_t);
+	const char *outpath = NULL;
+	uint8_t *buf;
+	int ch, ofd = STDOUT_FILENO;
+
+	optreset = 1;
+	optind = 1;
+	while ((ch = getopt(argc, argv, "o:")) != -1) {
+		switch (ch) {
+		case 'o':
+			outpath = optarg;
+			break;
+		default:
+			usage();
+		}
+	}
+
+	buf = malloc(total);
+	if (buf == NULL)
+		err(1, "malloc");
+
+	nvm_open(s, ifname, IFNVM_ACCESS_READ);
+	nvm_read_full(s, ifname, 0, total, buf, NULL);
+	nvm_close(s, ifname);
+
+	if (outpath != NULL) {
+		ofd = open(outpath, O_WRONLY | O_CREAT | O_TRUNC,
0644);
+		if (ofd == -1)
+			err(1, "open %s", outpath);
+	} else if (isatty(STDOUT_FILENO))
+		errx(1, "refusing to write binary NVM to a terminal; "
+		    "redirect stdout or use -o");
+
+	if (write(ofd, buf, total) != (ssize_t)total)
+		err(1, "write");
+	if (outpath != NULL)
+		close(ofd);
+
+	free(buf);
+	return (0);
+}
+
+static int
+cmd_show(int s, const char *ifname, int argc, char **argv)
+{
+	uint16_t words[64];	/* first 128 bytes of NVM */
+
+	(void)argc;
+	(void)argv;
+
+	nvm_open(s, ifname, IFNVM_ACCESS_READ);
+	nvm_read_full(s, ifname, 0, sizeof(words), words, NULL);
+	nvm_close(s, ifname);
+
+	printf("%s NVM header:\n", ifname);
+	printf("  control word 1:        0x%04x\n",
words[NVM_W_CONTROL1]);
+	printf("  pointer PCIe Analog:   0x%04x\n",
words[NVM_W_PCIE_ANALOG]);
+	printf("  pointer PHY Analog:    0x%04x\n",
words[NVM_W_PHY_ANALOG]);
+	printf("  pointer Option ROM:    0x%04x\n",
words[NVM_W_OPTION_ROM]);
+	printf("  pointer EMP Image:     0x%04x\n",
words[NVM_W_EMP_IMAGE]);
+	printf("  pointer PBA Block:     0x%04x\n",
words[NVM_W_PBA_BLOCK]);
+	printf("  pointer Perm SAN MAC:  0x%04x\n",
words[NVM_W_PERM_SAN_MAC]);
+	printf("  pointer VPD:           0x%04x\n", words[NVM_W_VPD]);
+	printf("  software checksum:     0x%04x\n",
words[NVM_W_SW_CHECKSUM]);
+
+	return (0);
+}
+
+/*
+ * Issue a single NVM_CFG_READ (datasheet 3.4.10.4) for the given
Feature_ID
+ * and dump the 6-byte response. This is the smallest user-visible
exercise
+ * of the kernel's ARQ-event-driven async completion path.
+ *
+ * Example: feature 0xFFF1 is the link mode selection
(1x40G/2x40G/4x10G).
+ */
+static int
+cmd_cfg_read(int s, const char *ifname, int argc, char **argv)
+{
+	struct if_nvmcmd nc;
+	uint8_t buf[IXL_NVM_CFG_ELEMENT_SIZE];
+	unsigned long ul;
+	uint16_t feature_id;
+	char *end;
+
+	if (argc != 2)
+		usage();
+
+	errno = 0;
+	ul = strtoul(argv[1], &end, 0);
+	if (errno != 0 || *end != '\0' || ul == 0 || ul > 0xffff)
+		errx(1, "invalid feature_id: %s", argv[1]);
+	feature_id = (uint16_t)ul;
+
+	/*
+	 * Datasheet 3.4.5.7 step 1 requires WRITE access on the NVM
+	 * resource before issuing NVM_CFG_READ, even though no write
+	 * happens.
+	 */
+	nvm_open(s, ifname, IFNVM_ACCESS_WRITE);
+
+	memset(&nc, 0, sizeof(nc));
+	if (strlcpy(nc.nc_ifname, ifname, sizeof(nc.nc_ifname)) >=
+	    sizeof(nc.nc_ifname))
+		errx(1, "interface name too long");
+	nc.nc_opcode = IXL_AQ_OP_NVM_CFG_READ;
+	nc.nc_cmdflags = 0;	/* single feature, feature mode */
+	nc.nc_module = 0;	/* reserved zero */
+	nc.nc_offset = feature_id;	/* bytes 20-21 of AQ cmd */
+	nc.nc_aqlen = 0;	/* element count filled in response */
+	nc.nc_buflen = sizeof(buf);
+	nc.nc_buf = buf;
+	nc.nc_flags = IFNVM_CMD_F_WAIT_ARQ;
+	nc.nc_timeout_ms = 5000;
+
+	{
+		int r = ioctl(s, SIOCSIFNVMCMD, &nc);
+		int saved = errno;
+		nvm_close(s, ifname);
+
+		printf("feature 0x%04x: ioctl=%d errno=%d "
+		    "AQ_retval=0x%04x elements=%u\n",
+		    feature_id, r, r == -1 ? saved : 0,
+		    nc.nc_retval, nc.nc_aqlen);
+		printf("  raw response:      %02x %02x %02x %02x %02x
%02x\n",
+		    buf[0], buf[1], buf[2], buf[3], buf[4], buf[5]);
+		if (r == -1)
+			return (1);
+	}
+
+	printf("  echo Feature_ID:   0x%04x\n", buf[0] | (buf[1] <<
8));
+	printf("  Feature options:   0x%04x\n", buf[2] | (buf[3] <<
8));
+	printf("  Feature selection: 0x%04x\n", buf[4] | (buf[5] <<
8));
+
+	return (0);
+}
+
+/*
+ * Exercise the write path and the kernel's ARQ event demultiplex.
+ *
+ * Reads word 0x16 (the PBA Block pointer in the NVM header;
documented
+ * as RW in datasheet 3.4.5.3), then writes the same value back via
+ * NVM_UPDATE with the Last_Command bit set. The chip schedules a bank
+ * swap and posts the completion on the ARQ; the kernel demultiplexes
+ * that event back to our sleeping SIOCSIFNVMCMD. Finally, read the
+ * word back and verify it matches.
+ *
+ * Identical-value write keeps the NVM software checksum (word 0x3F)
+ * valid, so there is no semantic change to the card.
+ */
+#define SELFTEST_WORD_OFFSET	0x16		/* PBA Block pointer
*/
+#define SELFTEST_BYTE_OFFSET	(SELFTEST_WORD_OFFSET * 2)
+
+static void
+cmd_one(int s, const char *ifname, struct if_nvmcmd *nc, const char
*what)
+{
+	if (ioctl(s, SIOCSIFNVMCMD, nc) == -1)
+		err(1, "%s: %s", ifname, what);
+	if (nc->nc_retval != 0)
+		errx(1, "%s: %s AQ retval=0x%04x", ifname, what, nc-
>nc_retval);
+}
+
+static int
+cmd_selftest(int s, const char *ifname, int argc, char **argv)
+{
+	struct if_nvmcmd nc;
+	uint16_t before, after;
+	int confirm = 0, ch;
+
+	optreset = 1;
+	optind = 1;
+	while ((ch = getopt(argc, argv, "y")) != -1) {
+		switch (ch) {
+		case 'y':
+			confirm = 1;
+			break;
+		default:
+			usage();
+		}
+	}
+
+	if (!confirm) {
+		fprintf(stderr,
+"ixlnvm selftest reads NVM word 0x%02x (the PBA Block pointer, an
RW\n"
+"NVM header word per datasheet 3.4.5.3), then writes the same value\n"
+"back via NVM_UPDATE with Last_Command set.  The chip triggers an\n"
+"NVM bank swap.  Content is semantically unchanged (identical-value\n"
+"write keeps the software checksum valid), but the bank-swap *is*\n"
+"a write to Flash.\n"
+"\n"
+"Rerun with -y to confirm.\n",
+		    SELFTEST_WORD_OFFSET);
+		return (1);
+	}
+
+	nvm_open(s, ifname, IFNVM_ACCESS_WRITE);
+
+	/* read the word */
+	memset(&nc, 0, sizeof(nc));
+	if (strlcpy(nc.nc_ifname, ifname, sizeof(nc.nc_ifname)) >=
+	    sizeof(nc.nc_ifname))
+		errx(1, "interface name too long");
+	nc.nc_opcode = IXL_AQ_OP_NVM_READ;
+	nc.nc_cmdflags = IXL_AQ_NVM_LAST_COMMAND;
+	nc.nc_offset = SELFTEST_BYTE_OFFSET;
+	nc.nc_aqlen = sizeof(before);
+	nc.nc_buflen = sizeof(before);
+	nc.nc_buf = &before;
+	cmd_one(s, ifname, &nc, "NVM_READ before");
+	printf("read word 0x%02x: 0x%04x\n", SELFTEST_WORD_OFFSET,
before);
+
+	/* write it back; wait for ARQ completion */
+	memset(&nc, 0, sizeof(nc));
+	if (strlcpy(nc.nc_ifname, ifname, sizeof(nc.nc_ifname)) >=
+	    sizeof(nc.nc_ifname))
+		errx(1, "interface name too long");
+	nc.nc_opcode = IXL_AQ_OP_NVM_UPDATE;
+	nc.nc_cmdflags = IXL_AQ_NVM_LAST_COMMAND;
+	nc.nc_module = 0;	/* flat Flash (first 64 KB -> shadow
RAM) */
+	nc.nc_offset = SELFTEST_BYTE_OFFSET;
+	nc.nc_aqlen = sizeof(before);
+	nc.nc_buflen = sizeof(before);
+	nc.nc_buf = &before;
+	nc.nc_flags = IFNVM_CMD_F_WAIT_ARQ;
+	nc.nc_timeout_ms = 30000;	/* 30 s; bank swap takes
~hundreds of ms */
+	cmd_one(s, ifname, &nc, "NVM_UPDATE");
+	printf("NVM_UPDATE completed (ARQ retval=0x%04x)\n",
nc.nc_retval);
+
+	/* read it back */
+	memset(&nc, 0, sizeof(nc));
+	if (strlcpy(nc.nc_ifname, ifname, sizeof(nc.nc_ifname)) >=
+	    sizeof(nc.nc_ifname))
+		errx(1, "interface name too long");
+	nc.nc_opcode = IXL_AQ_OP_NVM_READ;
+	nc.nc_cmdflags = IXL_AQ_NVM_LAST_COMMAND;
+	nc.nc_offset = SELFTEST_BYTE_OFFSET;
+	nc.nc_aqlen = sizeof(after);
+	nc.nc_buflen = sizeof(after);
+	nc.nc_buf = &after;
+	cmd_one(s, ifname, &nc, "NVM_READ after");
+
+	nvm_close(s, ifname);
+
+	if (after != before)
+		errx(1, "selftest FAILED: read-back 0x%04x != written
0x%04x",
+		    after, before);
+	printf("selftest PASSED: word 0x%02x = 0x%04x (unchanged)\n",
+	    SELFTEST_WORD_OFFSET, after);
+	return (0);
+}
+
+/*
+ * Read `length` bytes from the chip NVM at byte `offset` into `buf`,
+ * chunking through IXL_NVM_CHUNK-sized NVM_READ commands.  Prints a
+ * per-megabyte progress line to stderr.  Caller must hold an open
+ * NVM session.
+ */
+static void
+nvm_read_full(int s, const char *ifname, uint32_t offset, size_t
length,
+    void *buf, const char *label)
+{
+	uint8_t *p = buf;
+	size_t done = 0, reported = 0;
+
+	while (done < length) {
+		size_t remaining = length - done;
+		uint16_t chunk = (remaining > IXL_NVM_CHUNK) ?
+		    IXL_NVM_CHUNK : (uint16_t)remaining;
+		int last = (done + chunk >= length);
+
+		nvm_read(s, ifname, offset + done, chunk, p + done,
last);
+		done += chunk;
+
+		if (label != NULL &&
+		    (done - reported >= 1024 * 1024 || done ==
length)) {
+			fprintf(stderr, "  %s: %zu / %zu KB\r",
+			    label, done / 1024, length / 1024);
+			fflush(stderr);
+			reported = done;
+		}
+	}
+	if (label != NULL)
+		fprintf(stderr, "\n");
+}
+
+/*
+ * Intel NVM image parser.
+ *
+ * For 700-series controllers the .bin files in Intel's NVM update
+ * package are byte-for-byte raw Flash dumps (4, 5.8, or 8 MB,
+ * matching the chip's Flash size).  Module pointers in the NVM
+ * header decode two ways depending on bit 15 (datasheet 6.1.2):
+ *
+ *   ptr & 0x8000 = 1  ->  module is OUTSIDE shadow RAM.
+ *                         Value in bits 14:0 is a 4 KB sector index;
+ *                         byte_offset = (ptr & 0x7fff) * 4096.
+ *   ptr & 0x8000 = 0  ->  module is INSIDE shadow RAM.
+ *                         Value is a word offset;
+ *                         byte_offset = ptr * 2.
+ *
+ * Shadow-RAM modules begin with a size word per 6.1.5.1; outside-
+ * shadow modules have their own size field in the free-area
+ * mechanism and are not parsed here.  See datasheet table 6-2 for
+ * the full header map.
+ */
+
+enum nvm_flow {
+	FLOW_SHADOW,	/* RW modules mirrored to shadow RAM (3.4.5.3)
*/
+	FLOW_NONAUTH,	/* non-authenticated modules outside shadow
(3.4.5.4) */
+	FLOW_AUTH,	/* authenticated modules outside shadow
(3.4.5.5) */
+	FLOW_FREE,	/* free provisioning area pointer */
+};
+
+static const char *flow_names[] = {
+	[FLOW_SHADOW]	= "shadow",
+	[FLOW_NONAUTH]	= "non-auth",
+	[FLOW_AUTH]	= "auth",
+	[FLOW_FREE]	= "free-area",
+};
+
+struct nvm_module {
+	const char	*name;
+	uint16_t	 ptr_word;	/* word offset in NVM header
*/
+	enum nvm_flow	 flow;
+};
+
+/*
+ * Module pointers per datasheet table 6-2 (NVM header map).
+ * Words 0x60-0x67 are MinRRev values (data, not pointers).
+ */
+static const struct nvm_module nvm_modules[] = {
+	{ "PCIe Analog",		0x03, FLOW_AUTH },
+	{ "PHY Analog",			0x04, FLOW_AUTH },
+	{ "Option ROM",			0x05, FLOW_AUTH },
+	{ "RO PCIR Auto-load",		0x06, FLOW_SHADOW },
+	{ "Auto Generated Pointers",	0x07, FLOW_SHADOW },
+	{ "PCIR Auto-load",		0x08, FLOW_SHADOW },
+	{ "EMP Global",			0x09, FLOW_NONAUTH },
+	{ "RO PCIe LCB",		0x0a, FLOW_SHADOW },
+	{ "EMP Image",			0x0b, FLOW_AUTH },
+	{ "Manageability",		0x0e, FLOW_NONAUTH },
+	{ "EMP Settings",		0x0f, FLOW_NONAUTH },
+	{ "PBA Block",			0x16, FLOW_SHADOW },
+	{ "Boot Configuration",		0x17, FLOW_SHADOW },
+	{ "Permanent SAN MAC",		0x28, FLOW_SHADOW },
+	{ "VPD",			0x2f, FLOW_SHADOW },
+	{ "PXE Setup Options",		0x30, FLOW_SHADOW },
+	{ "PXE Custom Options",		0x31, FLOW_SHADOW },
+	{ "VLAN Configuration",		0x37, FLOW_SHADOW },
+	{ "POR Auto-load",		0x38, FLOW_SHADOW },
+	{ "Reserved EMPR Auto-load",	0x3a, FLOW_SHADOW },
+	{ "GLOBR Auto-load",		0x3b, FLOW_SHADOW },
+	{ "CORER Auto-load",		0x3c, FLOW_SHADOW },
+	{ "PHY Config Scripts",		0x3d, FLOW_NONAUTH },
+	{ "PCIe ALT Auto-load",		0x3e, FLOW_SHADOW },
+	{ "1st free area (1160KB)",	0x40, FLOW_FREE },
+	{ "NVM Image / 4th free area",	0x42, FLOW_FREE },
+	{ "3rd free area (16KB)",	0x44, FLOW_FREE },
+	{ "2nd free area (8KB)",	0x46, FLOW_FREE },
+	{ "EMP SR Settings",		0x48, FLOW_SHADOW },
+	{ "Feature Configuration",	0x49, FLOW_SHADOW },
+	{ "Core Mem Config",		0x4a, FLOW_SHADOW },
+	{ "FCoE Scratch Pad",		0x4b, FLOW_NONAUTH },
+	{ "Configuration Metadata",	0x4d, FLOW_NONAUTH },
+	{ "Immediate Fields",		0x4e, FLOW_SHADOW },
+	{ "External 25G PHY Global",	0x4f, FLOW_NONAUTH },
+	{ "SW-Data-Recovery",		0x59, FLOW_NONAUTH },
+	{ "PCIR-Data-Recovery",		0x5a, FLOW_SHADOW },
+	{ "Preservation Rules",		0x70, FLOW_NONAUTH },
+	{ "6th free area (4KB)",	0x71, FLOW_FREE },
+};
+
+static inline uint16_t
+nvm_word(const uint8_t *img, uint32_t word_offset)
+{
+	uint32_t b = word_offset * 2;
+	return (img[b] | ((uint16_t)img[b + 1] << 8));
+}
+
+/*
+ * Decode a header pointer value to a byte offset in NVM.
+ * Returns (uint32_t)-1 if the pointer is unset (0 or 0xffff).
+ */
+static inline uint32_t
+nvm_ptr_to_byte(uint16_t ptr)
+{
+	if (ptr == 0x0000 || ptr == 0xffff)
+		return ((uint32_t)-1);
+	if (ptr & 0x8000)
+		return ((uint32_t)(ptr & 0x7fff) * 4096);
+	return ((uint32_t)ptr * 2);
+}
+
+/*
+ * Compute the expected software checksum for an image, per datasheet
+ * 6.1.4.1.  The covered range is the 64 KB shadow RAM area; the VPD
+ * area and the PCIe ALT Auto-load module are skipped, as is the
+ * checksum word itself.  Returns 0xBABA - sum (mod 0x10000).
+ *
+ * The buffer must be at least NVM_SR_SIZE_WORDS * 2 bytes long.
+ */
+static uint16_t
+nvm_compute_checksum(const uint8_t *img)
+{
+	uint16_t sum = 0;
+	uint16_t vpd_ptr = nvm_word(img, NVM_W_VPD);
+	uint16_t pcie_alt_ptr = nvm_word(img, NVM_W_PCIE_ALT);
+	uint32_t vpd_lo = 0, vpd_hi = 0;
+	uint32_t alt_lo = 0, alt_hi = 0;
+	uint32_t w;
+
+	/* Only pointers inside shadow RAM (bit 15 clear) define a
skip. */
+	if (vpd_ptr != 0xffff && (vpd_ptr & 0x8000) == 0) {
+		vpd_lo = vpd_ptr;
+		vpd_hi = vpd_lo + NVM_CHECKSUM_VPD_SKIP_WORDS;
+	}
+	if (pcie_alt_ptr != 0xffff && (pcie_alt_ptr & 0x8000) == 0) {
+		alt_lo = pcie_alt_ptr;
+		alt_hi = alt_lo + NVM_CHECKSUM_PCIE_ALT_SKIP_WORDS;
+	}
+
+	for (w = 0; w < NVM_SR_SIZE_WORDS; w++) {
+		if (w == NVM_W_SW_CHECKSUM)
+			continue;
+		if (vpd_hi != 0 && w >= vpd_lo && w < vpd_hi)
+			continue;
+		if (alt_hi != 0 && w >= alt_lo && w < alt_hi)
+			continue;
+		sum += nvm_word(img, w);
+	}
+	return ((uint16_t)(NVM_SR_CHECKSUM_BASE - sum));
+}
+
+static int
+cmd_image_show(int s, const char *ifname, int argc, char **argv)
+{
+	const char *path;
+	int fd;
+	struct stat st;
+	uint8_t *img;
+	uint16_t ctrl1, checksum, pba_ptr;
+	uint16_t expected_checksum;
+	size_t i;
+
+	(void)s;
+	(void)ifname;
+
+	if (argc != 2)
+		usage();
+	path = argv[1];
+
+	fd = open(path, O_RDONLY);
+	if (fd == -1)
+		err(1, "open %s", path);
+	if (fstat(fd, &st) == -1)
+		err(1, "fstat %s", path);
+	if (st.st_size < 0x80 || st.st_size > 16 * 1024 * 1024)
+		errx(1, "%s: implausible NVM image size %lld bytes",
+		    path, (long long)st.st_size);
+
+	img = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+	if (img == MAP_FAILED)
+		err(1, "mmap %s", path);
+	close(fd);
+
+	ctrl1    = nvm_word(img, NVM_W_CONTROL1);
+	checksum = nvm_word(img, NVM_W_SW_CHECKSUM);
+	pba_ptr  = nvm_word(img, NVM_W_PBA_BLOCK);
+	expected_checksum = nvm_compute_checksum(img);
+
+	printf("image: %s\n", path);
+	printf("  size:               %lld bytes (%lld KB)\n",
+	    (long long)st.st_size, (long long)st.st_size / 1024);
+	printf("  control word 1:     0x%04x\n", ctrl1);
+	printf("  software checksum:  0x%04x (word 0x3f) %s\n",
+	    checksum,
+	    checksum == expected_checksum ? "[ok]" : "[MISMATCH]");
+	if (checksum != expected_checksum)
+		printf("  expected checksum:  0x%04x\n",
expected_checksum);
+
+	/* Firmware version (datasheet table 6-2 word 0x18, "Dev
Starter").
+	 * Encoding: bits 15:12 = major, bits 7:0 = minor (hex-
displayed).
+	 * So word 0x9057 prints as "9.57". */
+	{
+		uint16_t devstart = nvm_word(img,
NVM_W_DEV_STARTER_VERSION);
+		uint8_t major = (devstart >> 12) & 0xf;
+		uint8_t minor = devstart & 0xff;
+
+		printf("  firmware version:   %x.%02x (word 0x18 =
0x%04x)\n",
+		    major, minor, devstart);
+	}
+
+	/* Version metadata (datasheet table 6-2, words 0x29-0x2e). */
+	{
+		uint16_t map_ver = nvm_word(img, 0x29);
+		uint16_t nvm_img_ver = nvm_word(img, 0x2a);
+		uint16_t nvm_struct_ver = nvm_word(img, 0x2b);
+		uint32_t eetrack = (uint32_t)nvm_word(img,
NVM_W_EETRACK_LO) |
+		    ((uint32_t)nvm_word(img, NVM_W_EETRACK_HI) << 16);
+
+		printf("  map version:        0x%04x (word 0x29)\n",
map_ver);
+		printf("  NVM image version:  0x%04x (word 0x2a)\n",
+		    nvm_img_ver);
+		printf("  NVM structure ver:  0x%04x (word 0x2b)\n",
+		    nvm_struct_ver);
+		printf("  EETRACK ID:         0x%08x (words 0x2d-
0x2e)%s\n",
+		    eetrack,
+		    eetrack == 0xffffffff ? " [OEM image]" : "");
+	}
+
+	/*
+	 * OEM version is two words inside the Boot Config Block at
+	 * offset BOOT_CFG_OEM_VER_OFFSET.  It is only meaningful for
+	 * OEM images (EETRACK ID == 0xffffffff); for retail images
+	 * it stores combo image version info instead.
+	 */
+	{
+		uint16_t boot_cfg = nvm_word(img, NVM_W_BOOT_CONFIG);
+		uint32_t eetrack = (uint32_t)nvm_word(img,
NVM_W_EETRACK_LO) |
+		    ((uint32_t)nvm_word(img, NVM_W_EETRACK_HI) << 16);
+
+		if (boot_cfg != 0x0000 && boot_cfg != 0xffff &&
+		    (boot_cfg & 0x8000) == 0) {
+			uint32_t off = (uint32_t)boot_cfg +
+			    BOOT_CFG_OEM_VER_OFFSET;
+			if (((uint32_t)off + 1) * 2 <=
(uint32_t)st.st_size) {
+				uint16_t oem_hi = nvm_word(img, off);
+				uint16_t oem_lo = nvm_word(img, off +
1);
+				uint32_t oem_ver =
+				    ((uint32_t)oem_hi << 16) | oem_lo;
+				const char *label =
+				    eetrack == 0xffffffff ?
+				    "OEM version (raw):" :
+				    "combo image ver:   ";
+				printf("  %s 0x%08x (boot-config +
0x%x)\n",
+				    label, oem_ver,
BOOT_CFG_OEM_VER_OFFSET);
+			}
+		}
+	}
+
+	/*
+	 * Decode the PBA string if present.  A pointer of 0x0000 or
+	 * 0xffff means "no PBA in this image" (common in OEM-generic
+	 * images that aren't tied to a specific board).
+	 */
+	if (pba_ptr != 0xffff && pba_ptr != 0x0000) {
+		uint32_t pba_off = (uint32_t)pba_ptr * 2;
+		if (pba_off + 2 <= (uint32_t)st.st_size) {
+			uint16_t pba_size = nvm_word(img, pba_ptr);
+			uint32_t data_off = pba_off + 2;
+			uint32_t data_len = (pba_size > 1 ?
+			    (uint32_t)(pba_size - 1) * 2 : 0);
+			char pba[64];
+
+			if (data_len > sizeof(pba) - 1)
+				data_len = sizeof(pba) - 1;
+			if (data_off + data_len <=
(uint32_t)st.st_size) {
+				memcpy(pba, &img[data_off], data_len);
+				pba[data_len] = '\0';
+				printf("  PBA:                %s\n",
pba);
+			}
+		}
+	}
+
+	printf("\n%-28s %-5s %-6s %-12s %-8s %s\n",
+	    "module", "word", "ptr", "byte offset", "units", "flow");
+	printf("%-28s %-5s %-6s %-12s %-8s %s\n",
+	    "----------------------------",
+	    "----", "----", "-----------", "-----", "--------");
+	for (i = 0; i < nitems(nvm_modules); i++) {
+		const struct nvm_module *m = &nvm_modules[i];
+		uint16_t ptr = nvm_word(img, m->ptr_word);
+		uint32_t byte_off = nvm_ptr_to_byte(ptr);
+		const char *units;
+		char loc[20];
+
+		if (byte_off == (uint32_t)-1) {
+			snprintf(loc, sizeof(loc), "(unset)");
+			units = "";
+		} else if (byte_off < (uint32_t)st.st_size) {
+			snprintf(loc, sizeof(loc), "0x%08x",
byte_off);
+			units = (ptr & 0x8000) ? "4K sect" : "word";
+		} else {
+			snprintf(loc, sizeof(loc), "(out of range)");
+			units = (ptr & 0x8000) ? "4K sect" : "word";
+		}
+
+		printf("%-28s 0x%02x  0x%04x %-12s %-8s %s\n",
+		    m->name, m->ptr_word, ptr, loc, units,
+		    flow_names[m->flow]);
+	}
+
+	munmap(img, st.st_size);
+	return (0);
+}
+
+/* Look up an outside-shadow module's max size from module_table[]. */
+static uint32_t
+module_max_size(uint16_t ptr_word)
+{
+	size_t i;
+
+	for (i = 0; i < nitems(module_table); i++) {
+		if (module_table[i].update_ptr_word == ptr_word)
+			return (module_table[i].max_size_bytes);
+	}
+	return (0);
+}
+
+/*
+ * Preserved Field Area: card-identity modules that an image apply
+ * deliberately leaves untouched, so they are EXPECTED to differ from
+ * the image and must not be flagged as a failed update.
+ */
+static int
+module_is_pfa(uint16_t ptr_word)
+{
+	switch (ptr_word) {
+	case NVM_W_PBA_BLOCK:		/* 0x16 */
+	case NVM_W_BOOT_CONFIG:		/* 0x17 */
+	case NVM_W_PERM_SAN_MAC:	/* 0x28 */
+	case NVM_W_VPD:			/* 0x2f */
+	case 0x30:			/* PXE Setup Options */
+	case 0x31:			/* PXE Custom Options */
+	case 0x37:			/* VLAN Configuration */
+		return (1);
+	}
+	return (0);
+}
+
+/*
+ * Chip-managed modules: register auto-load tables and data-recovery
+ * blocks that the EMP firmware populates with computed/runtime state
+ * (register address/value snapshots, recovery validity bits).  A
+ * byte-for-byte match against the static image is neither expected
nor
+ * required: empirically these modules differ from the .bin by the
same
+ * bytes after a flash by Intel's own tool as after ours -- the differ
+ * signature is identical across firmware versions and flashing tools.
+ * They are reported as MANAGED and excluded from the pass/fail tally.
+ */
+static int
+module_is_managed(uint16_t ptr_word)
+{
+	switch (ptr_word) {
+	case 0x06:	/* RO PCIR Auto-load */
+	case 0x08:	/* PCIR Auto-load */
+	case 0x38:	/* POR Auto-load */
+	case 0x3a:	/* Reserved EMPR Auto-load */
+	case 0x3b:	/* GLOBR Auto-load */
+	case 0x3c:	/* CORER Auto-load */
+	case 0x59:	/* SW-Data-Recovery */
+	case 0x5a:	/* PCIR-Data-Recovery */
+		return (1);
+	}
+	return (0);
+}
+
+/*
+ * Module-aware verify (formerly a raw byte diff).  For each module
the
+ * tool knows how to update, resolve the module's location from the
+ * CHIP's own header pointer (NOT the image's -- after a per-module
+ * update + bank swap the chip stores the module at a different
physical
+ * offset than the factory image), read the module's bytes from the
+ * chip, and compare them to the image's copy of that module.
+ *
+ * This is the correct post-update oracle: a raw whole-flash byte diff
+ * is meaningless here because the dual-bank layout, free-area module
+ * placement, and preserved PFA all legitimately differ between the
+ * factory image and a per-module-updated chip.
+ *
+ * Shadow-RAM modules (bit 15 clear) live in the first 64 KB and are
+ * length-prefixed (first word = length in words).  Outside-shadow
+ * modules (bit 15 set) are sized from module_table[]'s
max_size_bytes.
+ * PFA modules are reported but not compared.
+ */
+static int
+cmd_image_diff(int s, const char *ifname, int argc, char **argv)
+{
+	const size_t sr_bytes = NVM_SR_SIZE_WORDS * sizeof(uint16_t);
+	const char *path;
+	int fd;
+	struct stat st;
+	uint8_t *img;
+	uint8_t shadow[NVM_SR_SIZE_WORDS * 2];
+	size_t i, n_match = 0, n_differ = 0, n_pfa = 0, n_absent = 0;
+	size_t n_skip = 0, n_managed = 0;
+
+	if (argc != 2)
+		usage();
+	path = argv[1];
+
+	fd = open(path, O_RDONLY);
+	if (fd == -1)
+		err(1, "open %s", path);
+	if (fstat(fd, &st) == -1)
+		err(1, "fstat %s", path);
+	if (st.st_size < (off_t)sr_bytes || st.st_size > 16 * 1024 *
1024)
+		errx(1, "%s: implausible NVM image size %lld",
+		    path, (long long)st.st_size);
+	img = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+	if (img == MAP_FAILED)
+		err(1, "mmap %s", path);
+	close(fd);
+
+	fprintf(stderr, "reading chip shadow RAM\n");
+	nvm_open(s, ifname, IFNVM_ACCESS_READ);
+	nvm_read_full(s, ifname, 0, sizeof(shadow), shadow, NULL);
+
+	printf("image: %s\n", path);
+	printf("chip:  %s\n", ifname);
+	printf("\nper-module comparison (chip pointer vs image
content):\n");
+
+	for (i = 0; i < nitems(nvm_modules); i++) {
+		const struct nvm_module *mod = &nvm_modules[i];
+		uint16_t img_ptr, chip_ptr;
+		uint32_t img_off, chip_off, len = 0;
+		uint8_t *chipbuf, *imgbuf;
+		uint32_t ndiff = 0, k, first = 0;
+		int managed;
+
+		if (mod->flow == FLOW_FREE)
+			continue;
+
+		if (module_is_pfa(mod->ptr_word)) {
+			printf("  %-26s %-9s PRESERVED (card
identity)\n",
+			    mod->name, flow_names[mod->flow]);
+			n_pfa++;
+			continue;
+		}
+
+		managed = module_is_managed(mod->ptr_word);
+
+		img_ptr = nvm_word(img, mod->ptr_word);
+		chip_ptr = nvm_word(shadow, mod->ptr_word);
+
+		if ((img_ptr == 0x0000 || img_ptr == 0xffff) &&
+		    (chip_ptr == 0x0000 || chip_ptr == 0xffff)) {
+			n_absent++;
+			continue;	/* absent on both sides; stay
quiet */
+		}
+		if (managed) {
+			/*
+			 * Chip-managed module: report MANAGED
regardless of
+			 * whether it happens to resolve/match. 
Differences
+			 * here are expected (firmware-populated) and
do not
+			 * count toward pass/fail.  Fall through to
attempt
+			 * the comparison only to annotate
match/differ.
+			 */
+		}
+		if (img_ptr == 0x0000 || img_ptr == 0xffff) {
+			if (managed) {
+				printf("  %-26s %-9s MANAGED    "
+				    "(chip-populated)\n", mod->name,
+				    flow_names[mod->flow]);
+				n_managed++;
+				continue;
+			}
+			printf("  %-26s %-9s ABSENT in image (chip has
it)\n",
+			    mod->name, flow_names[mod->flow]);
+			n_absent++;
+			continue;
+		}
+		if (chip_ptr == 0x0000 || chip_ptr == 0xffff) {
+			if (managed) {
+				printf("  %-26s %-9s MANAGED    "
+				    "(chip-populated)\n", mod->name,
+				    flow_names[mod->flow]);
+				n_managed++;
+				continue;
+			}
+			printf("  %-26s %-9s ABSENT on chip (image has
it)\n",
+			    mod->name, flow_names[mod->flow]);
+			n_differ++;
+			continue;
+		}
+
+		/* Determine the module length. */
+		if ((img_ptr & 0x8000) == 0) {
+			/* shadow-RAM module: first word = length in
words */
+			uint16_t lw = nvm_word(img, img_ptr);
+			if (lw == 0 || lw == 0xffff) {
+				if (managed) {
+					printf("  %-26s %-9s MANAGED   
"
+					    "(chip-populated)\n", mod-
>name,
+					    flow_names[mod->flow]);
+					n_managed++;
+					continue;
+				}
+				printf("  %-26s %-9s SKIP (no length
in "
+				    "image)\n", mod->name,
+				    flow_names[mod->flow]);
+				n_skip++;
+				continue;
+			}
+			len = ((uint32_t)lw + 1) * 2;
+		} else {
+			/* outside-shadow: size from module_table[] */
+			len = module_max_size(mod->ptr_word);
+			if (len == 0) {
+				if (managed) {
+					printf("  %-26s %-9s MANAGED   
"
+					    "(chip-populated)\n", mod-
>name,
+					    flow_names[mod->flow]);
+					n_managed++;
+					continue;
+				}
+				printf("  %-26s %-9s SKIP (size
unknown)\n",
+				    mod->name, flow_names[mod->flow]);
+				n_skip++;
+				continue;
+			}
+		}
+
+		img_off = nvm_ptr_to_byte(img_ptr);
+		chip_off = nvm_ptr_to_byte(chip_ptr);
+		if (img_off == (uint32_t)-1 ||
+		    (uint64_t)img_off + len > (uint64_t)st.st_size) {
+			if (managed) {
+				printf("  %-26s %-9s MANAGED    "
+				    "(chip-populated)\n", mod->name,
+				    flow_names[mod->flow]);
+				n_managed++;
+				continue;
+			}
+			printf("  %-26s %-9s SKIP (image range out of
"
+			    "bounds)\n", mod->name, flow_names[mod-
>flow]);
+			n_skip++;
+			continue;
+		}
+
+		/* Read the chip's copy from its own pointer location.
*/
+		chipbuf = malloc(len);
+		if (chipbuf == NULL)
+			err(1, "malloc %u", len);
+		if ((img_ptr & 0x8000) == 0 &&
+		    (uint64_t)chip_off + len <= sizeof(shadow)) {
+			/* shadow module already in our 64 KB buffer
*/
+			memcpy(chipbuf, shadow + chip_off, len);
+		} else {
+			nvm_read_full(s, ifname, chip_off, len,
chipbuf,
+			    len > 65536 ? mod->name : NULL);
+		}
+
+		imgbuf = img + img_off;
+		for (k = 0; k < len; k++) {
+			if (chipbuf[k] != imgbuf[k]) {
+				if (ndiff == 0)
+					first = k;
+				ndiff++;
+			}
+		}
+		free(chipbuf);
+
+		if (managed) {
+			if (ndiff == 0)
+				printf("  %-26s %-9s MANAGED    "
+				    "(%u bytes, matches)\n", mod-
>name,
+				    flow_names[mod->flow], len);
+			else
+				printf("  %-26s %-9s MANAGED    "
+				    "(%u bytes, %u differ, chip-
populated)\n",
+				    mod->name, flow_names[mod->flow],
len,
+				    ndiff);
+			n_managed++;
+		} else if (ndiff == 0) {
+			printf("  %-26s %-9s MATCH      (%u bytes)\n",
+			    mod->name, flow_names[mod->flow], len);
+			n_match++;
+		} else {
+			printf("  %-26s %-9s DIFFER     (%u bytes, %u
"
+			    "differ, first +0x%x)\n", mod->name,
+			    flow_names[mod->flow], len, ndiff, first);
+			n_differ++;
+		}
+	}
+
+	nvm_close(s, ifname);
+
+	printf("\nsummary: %zu match, %zu differ, %zu managed, "
+	    "%zu preserved, %zu absent, %zu skipped\n",
+	    n_match, n_differ, n_managed, n_pfa, n_absent, n_skip);
+	printf("note: 'managed' modules are chip-populated
register/recovery\n");
+	printf("  state; they differ from the static image by design
and are\n");
+	printf("  not a sign of an incomplete update.\n");
+	if (n_differ > 0)
+		printf("note: 'differ' on a module the image carries
means "
+		    "that module is not yet updated on the chip.\n");
+
+	munmap(img, st.st_size);
+	return (n_differ > 0 ? 1 : 0);
+}
+
+/*
+ * Parser for Intel's nvmupdate.cfg manifest.  The file is plain
+ * text, one device record per BEGIN DEVICE / END DEVICE block,
+ * with KEY: value lines inside.  We capture the fields we need
+ * for image matching: vendor/device IDs, the .bin image filename,
+ * the EEPID (= EETRACK ID this image upgrades TO), and the
+ * REPLACES list (EETRACK IDs this image can upgrade FROM).
+ */
+
+struct nvmcfg_entry {
+	char		 devicename[64];
+	uint16_t	 vendor;
+	uint16_t	 device;
+	char		 nvm_image[256];
+	char		 orom_image[256];
+	uint32_t	 eepid;
+	uint32_t	*replaces;
+	size_t		 nreplaces;
+	int		 reset_power;	/* 1 = POWER, 0 = REBOOT/unset
*/
+};
+
+struct nvmcfg {
+	struct nvmcfg_entry	*entries;
+	size_t			 nentries;
+	size_t			 capacity;
+};
+
+static void
+nvmcfg_free(struct nvmcfg *cfg)
+{
+	size_t i;
+
+	if (cfg == NULL)
+		return;
+	for (i = 0; i < cfg->nentries; i++)
+		free(cfg->entries[i].replaces);
+	free(cfg->entries);
+	free(cfg);
+}
+
+/* Trim leading whitespace; return start of trimmed string. */
+static char *
+ltrim(char *s)
+{
+	while (*s == ' ' || *s == '\t')
+		s++;
+	return (s);
+}
+
+/* Trim trailing whitespace + \r\n in place. */
+static void
+rtrim(char *s)
+{
+	size_t n = strlen(s);
+
+	while (n > 0 && (s[n - 1] == ' ' || s[n - 1] == '\t' ||
+	    s[n - 1] == '\r' || s[n - 1] == '\n'))
+		s[--n] = '\0';
+}
+
+/* Match "KEY:" at start of line; returns pointer to value (trimmed)
or NULL. */
+static char *
+keyval(char *line, const char *key)
+{
+	size_t klen = strlen(key);
+
+	if (strncmp(line, key, klen) != 0)
+		return (NULL);
+	if (line[klen] != ':')
+		return (NULL);
+	return (ltrim(line + klen + 1));
+}
+
+static void
+nvmcfg_parse_replaces(struct nvmcfg_entry *e, char *value)
+{
+	char *tok, *save;
+	size_t cap = 4;
+
+	e->replaces = malloc(cap * sizeof(uint32_t));
+	if (e->replaces == NULL)
+		err(1, "malloc");
+
+	for (tok = strtok_r(value, " \t", &save); tok != NULL;
+	    tok = strtok_r(NULL, " \t", &save)) {
+		uint32_t v;
+		char *end;
+
+		errno = 0;
+		v = (uint32_t)strtoul(tok, &end, 16);
+		if (errno != 0 || *end != '\0')
+			continue;
+		if (e->nreplaces == cap) {
+			cap *= 2;
+			e->replaces = reallocarray(e->replaces, cap,
+			    sizeof(uint32_t));
+			if (e->replaces == NULL)
+				err(1, "reallocarray");
+		}
+		e->replaces[e->nreplaces++] = v;
+	}
+}
+
+static struct nvmcfg *
+nvmcfg_load(const char *path)
+{
+	FILE *fp;
+	char *line = NULL;
+	size_t cap = 0;
+	ssize_t len;
+	struct nvmcfg *cfg;
+	struct nvmcfg_entry *e = NULL;
+	int in_block = 0;
+
+	fp = fopen(path, "r");
+	if (fp == NULL)
+		err(1, "open %s", path);
+
+	cfg = calloc(1, sizeof(*cfg));
+	if (cfg == NULL)
+		err(1, "calloc");
+
+	while ((len = getline(&line, &cap, fp)) != -1) {
+		char *p = ltrim(line);
+		char *v;
+
+		rtrim(p);
+		if (*p == '\0' || *p == ';')
+			continue;
+
+		if (strcmp(p, "BEGIN DEVICE") == 0) {
+			if (cfg->nentries == cfg->capacity) {
+				size_t newcap = cfg->capacity ?
+				    cfg->capacity * 2 : 16;
+				cfg->entries = reallocarray(cfg-
>entries,
+				    newcap, sizeof(*cfg->entries));
+				if (cfg->entries == NULL)
+					err(1, "reallocarray");
+				cfg->capacity = newcap;
+			}
+			e = &cfg->entries[cfg->nentries];
+			memset(e, 0, sizeof(*e));
+			in_block = 1;
+			continue;
+		}
+		if (strcmp(p, "END DEVICE") == 0) {
+			if (in_block && e != NULL)
+				cfg->nentries++;
+			in_block = 0;
+			e = NULL;
+			continue;
+		}
+		if (!in_block || e == NULL)
+			continue;
+
+		if ((v = keyval(p, "DEVICENAME")) != NULL)
+			strlcpy(e->devicename, v, sizeof(e-
>devicename));
+		else if ((v = keyval(p, "VENDOR")) != NULL)
+			e->vendor = (uint16_t)strtoul(v, NULL, 16);
+		else if ((v = keyval(p, "DEVICE")) != NULL)
+			e->device = (uint16_t)strtoul(v, NULL, 16);
+		else if ((v = keyval(p, "NVM IMAGE")) != NULL)
+			strlcpy(e->nvm_image, v, sizeof(e-
>nvm_image));
+		else if ((v = keyval(p, "OROM IMAGE")) != NULL)
+			strlcpy(e->orom_image, v, sizeof(e-
>orom_image));
+		else if ((v = keyval(p, "EEPID")) != NULL)
+			e->eepid = (uint32_t)strtoul(v, NULL, 16);
+		else if ((v = keyval(p, "REPLACES")) != NULL)
+			nvmcfg_parse_replaces(e, v);
+		else if ((v = keyval(p, "RESET TYPE")) != NULL)
+			e->reset_power = (strcmp(v, "POWER") == 0);
+	}
+
+	free(line);
+	fclose(fp);
+	return (cfg);
+}
+
+/*
+ * Search the cfg for an entry whose EEPID equals the chip's EETRACK
ID
+ * (meaning the chip is already at that image), or whose REPLACES list
+ * contains it (meaning this image can upgrade the chip).  Returns
NULL
+ * if no match.  Direct EEPID match takes precedence.
+ */
+static const struct nvmcfg_entry *
+nvmcfg_find(const struct nvmcfg *cfg, uint32_t eepid, int
*via_replaces)
+{
+	size_t i, j;
+
+	*via_replaces = 0;
+	/* Exact match first */
+	for (i = 0; i < cfg->nentries; i++) {
+		if (cfg->entries[i].eepid == eepid)
+			return (&cfg->entries[i]);
+	}
+	/* Then REPLACES */
+	for (i = 0; i < cfg->nentries; i++) {
+		for (j = 0; j < cfg->entries[i].nreplaces; j++) {
+			if (cfg->entries[i].replaces[j] == eepid) {
+				*via_replaces = 1;
+				return (&cfg->entries[i]);
+			}
+		}
+	}
+	return (NULL);
+}
+
+/*
+ * Read the chip's EETRACK ID via a short NVM read (4 bytes from
+ * byte offset 0x5a = word 0x2d).  Holds an open NVM session.
+ */
+static uint32_t
+chip_read_eetrack(int s, const char *ifname)
+{
+	uint16_t words[2];
+
+	nvm_open(s, ifname, IFNVM_ACCESS_READ);
+	nvm_read(s, ifname, NVM_W_EETRACK_LO * 2, sizeof(words),
words, 1);
+	nvm_close(s, ifname);
+	return ((uint32_t)words[0] | ((uint32_t)words[1] << 16));
+}
+
+static int
+cmd_match(int s, const char *ifname, int argc, char **argv)
+{
+	const char *cfgpath = NULL;
+	const char *eepid_str = NULL;
+	uint32_t eepid;
+	const struct nvmcfg_entry *e;
+	struct nvmcfg *cfg;
+	int via_replaces, ch;
+
+	optreset = 1;
+	optind = 1;
+	while ((ch = getopt(argc, argv, "c:e:")) != -1) {
+		switch (ch) {
+		case 'c':
+			cfgpath = optarg;
+			break;
+		case 'e':
+			eepid_str = optarg;
+			break;
+		default:
+			usage();
+		}
+	}
+
+	if (cfgpath == NULL)
+		usage();
+	if (eepid_str == NULL && ifname == NULL) {
+		warnx("specify -e <eepid> or -i <ifname>");
+		usage();
+	}
+
+	if (eepid_str != NULL) {
+		char *end;
+		errno = 0;
+		eepid = (uint32_t)strtoul(eepid_str, &end, 16);
+		if (errno != 0 || *end != '\0')
+			errx(1, "invalid EEPID: %s", eepid_str);
+	} else {
+		eepid = chip_read_eetrack(s, ifname);
+		printf("%s EETRACK ID: 0x%08x\n", ifname, eepid);
+	}
+
+	cfg = nvmcfg_load(cfgpath);
+	if (cfg->nentries == 0)
+		errx(1, "%s: no devices parsed", cfgpath);
+
+	e = nvmcfg_find(cfg, eepid, &via_replaces);
+	if (e == NULL) {
+		printf("No match for EEPID 0x%08x in %s (%zu entries
scanned)\n",
+		    eepid, cfgpath, cfg->nentries);
+		nvmcfg_free(cfg);
+		return (1);
+	}
+
+	printf("matched: %s (%04x:%04x)\n",
+	    e->devicename, e->vendor, e->device);
+	printf("  NVM image:   %s\n", e->nvm_image);
+	if (e->orom_image[0] != '\0')
+		printf("  OROM image:  %s\n", e->orom_image);
+	printf("  EEPID:       0x%08x%s\n", e->eepid,
+	    via_replaces ? " (chip needs upgrade to this)" :
+	    " (chip is already at this image)");
+	printf("  reset type:  %s\n", e->reset_power ? "POWER" :
"REBOOT");
+	if (e->nreplaces > 0) {
+		size_t i;
+		printf("  replaces:   ");
+		for (i = 0; i < e->nreplaces; i++)
+			printf(" 0x%08x", e->replaces[i]);
+		printf("\n");
+	}
+
+	nvmcfg_free(cfg);
+	return (0);
+}
+
+/*
+ * Enumerate ixl(4) interfaces via getifaddrs(3), deduplicate, and
+ * return a malloc'd array of strdup'd names.  Caller frees with
+ * free_ixl_interfaces().
+ */
+static int
+list_ixl_interfaces(char ***out_names, size_t *out_n)
+{
+	struct ifaddrs *ifap = NULL, *ifa;
+	char **names = NULL;
+	size_t n = 0, cap = 0;
+
+	if (getifaddrs(&ifap) != 0)
+		return (-1);
+	for (ifa = ifap; ifa != NULL; ifa = ifa->ifa_next) {
+		size_t i;
+
+		if (strncmp(ifa->ifa_name, "ixl", 3) != 0)
+			continue;
+		if (!isdigit((unsigned char)ifa->ifa_name[3]))
+			continue;
+		for (i = 0; i < n; i++) {
+			if (strcmp(names[i], ifa->ifa_name) == 0)
+				break;
+		}
+		if (i < n)
+			continue;
+		if (n == cap) {
+			cap = cap ? cap * 2 : 8;
+			names = reallocarray(names, cap,
sizeof(*names));
+			if (names == NULL)
+				err(1, "reallocarray");
+		}
+		names[n] = strdup(ifa->ifa_name);
+		if (names[n] == NULL)
+			err(1, "strdup");
+		n++;
+	}
+	freeifaddrs(ifap);
+
+	/* simple insertion sort so output is deterministic */
+	{
+		size_t i, j;
+		for (i = 1; i < n; i++) {
+			char *cur = names[i];
+			for (j = i; j > 0 &&
+			    strcmp(names[j - 1], cur) > 0; j--)
+				names[j] = names[j - 1];
+			names[j] = cur;
+		}
+	}
+	*out_names = names;
+	*out_n = n;
+	return (0);
+}
+
+static void
+free_ixl_interfaces(char **names, size_t n)
+{
+	size_t i;
+
+	for (i = 0; i < n; i++)
+		free(names[i]);
+	free(names);
+}
+
+/*
+ * Tolerant NVM session open: returns 0 on success, -errno on failure.
+ * Used by scan paths that need to skip interfaces that fail to open
+ * (e.g. another process already holds the session).
+ */
+static int
+nvm_try_open(int s, const char *ifname, uint8_t access)
+{
+	struct if_nvmsess ns;
+
+	memset(&ns, 0, sizeof(ns));
+	if (strlcpy(ns.ns_ifname, ifname, sizeof(ns.ns_ifname)) >=
+	    sizeof(ns.ns_ifname))
+		return (-ENAMETOOLONG);
+	ns.ns_access = access;
+	if (ioctl(s, SIOCSIFNVMOPEN, &ns) == -1)
+		return (-errno);
+	return (0);
+}
+
+/*
+ * Read the NVM image version word (0x18) and EETRACK ID (0x2d / 0x2e)
+ * from the chip's NVM, and the running EMP firmware version via the
+ * SIOCGIFFWVER ioctl (cached at driver attach from AQ Get Version).
+ * Holds its own short-lived read session for the NVM reads.  Returns
+ * 0 on success or -errno on failure.
+ */
+static int
+read_chip_versions(int s, const char *ifname, uint16_t *devstart,
+    uint32_t *eetrack, struct if_fwver *fwver)
+{
+	uint16_t buf[2];
+	int rv;
+
+	rv = nvm_try_open(s, ifname, IFNVM_ACCESS_READ);
+	if (rv != 0)
+		return (rv);
+
+	nvm_read(s, ifname, NVM_W_DEV_STARTER_VERSION * 2,
+	    sizeof(*devstart), devstart, 0);
+	nvm_read(s, ifname, NVM_W_EETRACK_LO * 2, sizeof(buf), buf,
1);
+	nvm_close(s, ifname);
+
+	*eetrack = (uint32_t)buf[0] | ((uint32_t)buf[1] << 16);
+
+	memset(fwver, 0, sizeof(*fwver));
+	if (strlcpy(fwver->fv_ifname, ifname, sizeof(fwver-
>fv_ifname)) >=
+	    sizeof(fwver->fv_ifname))
+		return (-ENAMETOOLONG);
+	if (ioctl(s, SIOCGIFFWVER, fwver) == -1)
+		return (-errno);
+	return (0);
+}
+
+/*
+ * Per-card record (one entry per physical PCIe controller).  Multiple
+ * port interfaces of the same chip share one entry, with ports[]
+ * holding the interface names (sorted).
+ */
+struct card_entry {
+	uint16_t	 pci_bus;
+	uint16_t	 pci_dev;	/* function differs per port
*/
+	uint16_t	 devstart;	/* NVM image version word */
+	uint32_t	 eetrack;
+	struct if_fwver fwver;		/* from first port read */
+	char		**ports;
+	size_t		 nports;
+	size_t		 ports_cap;
+	int		 err;		/* -errno from version read; 0
OK */
+	const struct nvmcfg_entry *match;
+	int		 via_replaces;
+	const char	*status;
+	const char	*bin;
+	const char	*reset;
+};
+
+static void
+card_add_port(struct card_entry *c, const char *ifname)
+{
+	if (c->nports == c->ports_cap) {
+		c->ports_cap = c->ports_cap ? c->ports_cap * 2 : 4;
+		c->ports = reallocarray(c->ports, c->ports_cap,
+		    sizeof(*c->ports));
+		if (c->ports == NULL)
+			err(1, "reallocarray");
+	}
+	c->ports[c->nports] = strdup(ifname);
+	if (c->ports[c->nports] == NULL)
+		err(1, "strdup");
+	c->nports++;
+}
+
+/*
+ * scan / default subcommand: walk every ixl(4) interface, read its
+ * firmware + EETRACK + PCIe location, group ports of the same
physical
+ * card together (matching on PCIe bus:dev; function differs per
port),
+ * and (if a nvmupdate.cfg is found in the working directory or
supplied
+ * via -c) match each card against the manifest.  Per card we print a
+ * single status block listing all of its ports and, where an upgrade
is
+ * possible and the .bin file exists, the exact command to apply.
+ *
+ * Output is human-readable by default; -q switches to a stable
+ * one-line-per-card machine format with comma-separated port names:
+ *
+ *   ports  nvm-ver  fw-ver  eetrack  status  bin  reset
+ *
+ * Status values: CURRENT, UPGRADE, NO_MATCH, MISSING_BIN, NO_CFG,
ERROR.
+ */
+static int
+cmd_scan(int argc, char **argv)
+{
+	const char *cfgpath = "nvmupdate.cfg";
+	int quiet = 0, ch, s;
+	char **ifs = NULL;
+	size_t nifs = 0, i, j;
+	struct nvmcfg *cfg = NULL;
+	struct stat st;
+	int n_upgrade = 0, n_current = 0, n_nomatch = 0;
+	int n_missing = 0, n_error = 0;
+	struct card_entry *cards = NULL;
+	size_t ncards = 0, cards_cap = 0;
+
+	optreset = 1;
+	optind = 1;
+	while ((ch = getopt(argc, argv, "c:q")) != -1) {
+		switch (ch) {
+		case 'c':
+			cfgpath = optarg;
+			break;
+		case 'q':
+			quiet = 1;
+			break;
+		default:
+			usage();
+		}
+	}
+
+	s = socket(AF_INET, SOCK_DGRAM, 0);
+	if (s == -1)
+		err(1, "socket");
+
+	if (list_ixl_interfaces(&ifs, &nifs) != 0)
+		err(1, "getifaddrs");
+
+	if (stat(cfgpath, &st) == 0)
+		cfg = nvmcfg_load(cfgpath);
+
+	if (!quiet) {
+		printf("scanning ixl(4) interfaces");
+		if (cfg != NULL)
+			printf(" against %s (%zu entries)",
+			    cfgpath, cfg->nentries);
+		else
+			printf("; %s not found, inventory only",
+			    cfgpath);
+		printf("\n\n");
+	}
+
+	if (nifs == 0) {
+		if (!quiet)
+			printf("no ixl(4) interfaces found.\n");
+		goto out;
+	}
+
+	/*
+	 * First pass: read versions and PCIe location for each
+	 * interface, then attach it to (or create) its card_entry.
+	 */
+	for (i = 0; i < nifs; i++) {
+		struct if_fwver fwver;
+		uint16_t devstart = 0;
+		uint32_t eetrack = 0;
+		struct card_entry *c = NULL;
+		int rv;
+
+		rv = read_chip_versions(s, ifs[i], &devstart,
&eetrack,
+		    &fwver);
+		if (rv != 0) {
+			/* Card entry keyed by ifname only when read
fails;
+			 * we can't group it. */
+			if (ncards == cards_cap) {
+				cards_cap = cards_cap ? cards_cap * 2
: 8;
+				cards = reallocarray(cards, cards_cap,
+				    sizeof(*cards));
+				if (cards == NULL)
+					err(1, "reallocarray");
+			}
+			memset(&cards[ncards], 0,
sizeof(cards[ncards]));
+			cards[ncards].err = rv;
+			card_add_port(&cards[ncards], ifs[i]);
+			ncards++;
+			n_error++;
+			continue;
+		}
+
+		for (j = 0; j < ncards; j++) {
+			if (cards[j].err != 0)
+				continue;
+			if (cards[j].pci_bus == fwver.fv_pci_bus &&
+			    cards[j].pci_dev == fwver.fv_pci_dev) {
+				c = &cards[j];
+				break;
+			}
+		}
+		if (c != NULL) {
+			card_add_port(c, ifs[i]);
+			continue;
+		}
+
+		if (ncards == cards_cap) {
+			cards_cap = cards_cap ? cards_cap * 2 : 8;
+			cards = reallocarray(cards, cards_cap,
+			    sizeof(*cards));
+			if (cards == NULL)
+				err(1, "reallocarray");
+		}
+		c = &cards[ncards++];
+		memset(c, 0, sizeof(*c));
+		c->pci_bus = fwver.fv_pci_bus;
+		c->pci_dev = fwver.fv_pci_dev;
+		c->devstart = devstart;
+		c->eetrack = eetrack;
+		c->fwver = fwver;
+		card_add_port(c, ifs[i]);
+
+		if (cfg != NULL)
+			c->match = nvmcfg_find(cfg, eetrack,
+			    &c->via_replaces);
+		if (cfg == NULL) {
+			c->status = "NO_CFG";
+			c->bin = "-";
+			c->reset = "-";
+		} else if (c->match == NULL) {
+			c->status = "NO_MATCH";
+			c->bin = "-";
+			c->reset = "-";
+			n_nomatch++;
+		} else if (!c->via_replaces) {
+			c->status = "CURRENT";
+			c->bin = c->match->nvm_image;
+			c->reset = c->match->reset_power ? "POWER" :
+			    "REBOOT";
+			n_current++;
+		} else {
+			c->bin = c->match->nvm_image;
+			c->reset = c->match->reset_power ? "POWER" :
+			    "REBOOT";
+			if (stat(c->match->nvm_image, &st) == 0) {
+				c->status = "UPGRADE";
+				n_upgrade++;
+			} else {
+				c->status = "MISSING_BIN";
+				n_missing++;
+			}
+		}
+	}
+
+	/* Second pass: print per-card. */
+	for (i = 0; i < ncards; i++) {
+		struct card_entry *c = &cards[i];
+		char joined[256];
+		size_t off = 0;
+
+		joined[0] = '\0';
+		for (j = 0; j < c->nports; j++) {
+			int n = snprintf(joined + off, sizeof(joined)
- off,
+			    "%s%s", j ? "," : "", c->ports[j]);
+			if (n < 0 || (size_t)n >= sizeof(joined) -
off)
+				break;
+			off += n;
+		}
+
+		if (c->err != 0) {
+			if (quiet) {
+				printf("%s -.-- -.-.----- ---------- "
+				    "ERROR - -\n", joined);
+			} else {
+				printf("%s  ERROR  could not read NVM
(%s)\n",
+				    joined, strerror(-c->err));
+			}
+			continue;
+		}
+
+		if (quiet) {
+			printf("%s %x.%02x %u.%u.%05u 0x%08x %s %s
%s\n",
+			    joined,
+			    (c->devstart >> 12) & 0xf, c->devstart &
0xff,
+			    c->fwver.fv_fw_major, c-
>fwver.fv_fw_minor,
+			    c->fwver.fv_fw_build, c->eetrack, c-
>status,
+			    c->bin, c->reset);
+			continue;
+		}
+
+		printf("%s  (pci %u:%u, %zu port%s)\n", joined,
+		    c->pci_bus, c->pci_dev, c->nports,
+		    c->nports == 1 ? "" : "s");
+		printf("           nvm %x.%02x  fw %u.%u.%05u  "
+		    "eetrack 0x%08x  %s\n",
+		    (c->devstart >> 12) & 0xf, c->devstart & 0xff,
+		    c->fwver.fv_fw_major, c->fwver.fv_fw_minor,
+		    c->fwver.fv_fw_build, c->eetrack, c->status);
+		if (strcmp(c->status, "UPGRADE") == 0) {
+			printf("           upgrade to %s (reset
%s)\n",
+			    c->match->nvm_image, c->reset);
+			printf("           apply:  ixlnvm -i %s "
+			    "image-apply -f %s -y\n",
+			    c->ports[0], c->match->nvm_image);
+		} else if (strcmp(c->status, "MISSING_BIN") == 0) {
+			printf("           upgrade to %s available but
"
+			    "%s not found in working directory\n",
+			    c->match->nvm_image, c->match->nvm_image);
+		} else if (strcmp(c->status, "CURRENT") == 0) {
+			printf("           at target image %s\n",
+			    c->match->nvm_image);
+		}
+	}
+
+	/* free card_entry contents */
+	for (i = 0; i < ncards; i++) {
+		for (j = 0; j < cards[i].nports; j++)
+			free(cards[i].ports[j]);
+		free(cards[i].ports);
+	}
+	free(cards);
+
+	if (!quiet) {
+		printf("\nsummary: %d upgrade, %d current, %d no-
match, "
+		    "%d missing-bin, %d error\n",
+		    n_upgrade, n_current, n_nomatch, n_missing,
n_error);
+	}
+
+out:
+	if (cfg != NULL)
+		nvmcfg_free(cfg);
+	free_ixl_interfaces(ifs, nifs);
+	close(s);
+	return (n_upgrade > 0 ? 0 : (n_error > 0 ? 2 : 0));
+}
+
+/*
+ * Read the chip's shadow RAM (first 64 KB) and verify the software
+ * checksum at word 0x3f against the value our nvm_compute_checksum()
+ * derives from the same data.  A mismatch on a live, working card
+ * would mean either the chip is in an inconsistent NVM state
(unlikely
+ * if the driver attaches normally) or our checksum algorithm is
wrong.
+ */
+static int
+cmd_verify_checksum(int s, const char *ifname, int argc, char **argv)
+{
+	const size_t bytes = NVM_SR_SIZE_WORDS * sizeof(uint16_t);
+	uint8_t *buf;
+	uint16_t actual, expected;
+	int match;
+
+	(void)argc;
+	(void)argv;
+
+	buf = malloc(bytes);
+	if (buf == NULL)
+		err(1, "malloc");
+
+	nvm_open(s, ifname, IFNVM_ACCESS_READ);
+	nvm_read_full(s, ifname, 0, bytes, buf, "shadow RAM");
+	nvm_close(s, ifname);
+
+	actual = (uint16_t)buf[NVM_W_SW_CHECKSUM * 2] |
+	    ((uint16_t)buf[NVM_W_SW_CHECKSUM * 2 + 1] << 8);
+	expected = nvm_compute_checksum(buf);
+	match = (actual == expected);
+
+	printf("%s shadow RAM software checksum:\n", ifname);
+	printf("  stored at word 0x3f: 0x%04x\n", actual);
+	printf("  computed:            0x%04x\n", expected);
+	printf("  result:              %s\n", match ? "match" :
"MISMATCH");
+
+	free(buf);
+	return (match ? 0 : 1);
+}
+
+/*
+ * Issue an NVM_Update AQ command via the kernel tunnel, with the
+ * given module_pointer, offset, length, command_flags, and buffer
+ * direction (k -> chip).  The kernel auto-sets the FE flag on
+ * non-LAST commands.  Returns the AQ retval the chip reported.
+ *
+ * If wait_arq is set, the kernel will sleep for the chip's async
+ * ARQ completion event before returning.  Used for the final
+ * command of an update sequence (LAST_COMMAND set).
+ */
+static int
+nvm_update_chunk(int s, const char *ifname, uint8_t module_pointer,
+    uint32_t byte_offset, uint16_t length, uint8_t cmdflags,
+    const void *data, int wait_arq, uint16_t timeout_ms)
+{
+	struct if_nvmcmd nc;
+
+	memset(&nc, 0, sizeof(nc));
+	if (strlcpy(nc.nc_ifname, ifname, sizeof(nc.nc_ifname)) >=
+	    sizeof(nc.nc_ifname))
+		errx(1, "interface name too long");
+	nc.nc_opcode = IXL_AQ_OP_NVM_UPDATE;
+	nc.nc_module = module_pointer;
+	nc.nc_cmdflags = cmdflags;
+	nc.nc_offset = byte_offset;
+	nc.nc_aqlen = length;
+	nc.nc_buflen = length;
+	nc.nc_buf = (void *)(uintptr_t)data;
+	if (wait_arq) {
+		nc.nc_flags = IFNVM_CMD_F_WAIT_ARQ;
+		nc.nc_timeout_ms = timeout_ms;
+	}
+
+	if (ioctl(s, SIOCSIFNVMCMD, &nc) == -1)
+		err(1, "%s: NVM_UPDATE module=%02x offset=0x%x",
ifname,
+		    module_pointer, byte_offset);
+	return (nc.nc_retval);
+}
+
+/*
+ * Apply an Intel NVM image via the flat NVM update flow (datasheet
+ * 3.4.5.6).  Stages the image's first 64 KB into the chip's NVM
+ * Image area via NVM_Update commands with module_pointer=0x42,
+ * then issues a final command with LAST_COMMAND | REARRANGE_TO_FLAT
+ * and waits for the chip's bank-swap completion on the ARQ.
+ *
+ * The chip's firmware handles preservation of card identity (MAC,
+ * VPD, PBA, etc.) via the PFA mechanism, and recomputes the
+ * software checksum.  We do not need to compute either ourselves.
+ *
+ * Without -y, this command is a dry run: validates the image and
+ * prints the staging plan but does not touch the chip.
+ */
+static int
+cmd_image_apply(int s, const char *ifname, int argc, char **argv)
+{
+	const size_t sr_bytes = NVM_SR_SIZE_WORDS * sizeof(uint16_t);
+	const char *path = NULL;
+	int confirm = 0, do_shadow = 0, ch, fd;
+	struct stat st;
+	uint8_t *img;
+	uint16_t stored_cs, expected_cs, devstart;
+	uint32_t img_eetrack;
+
+	optreset = 1;
+	optind = 1;
+	while ((ch = getopt(argc, argv, "f:sy")) != -1) {
+		switch (ch) {
+		case 'f':
+			path = optarg;
+			break;
+		case 's':
+			do_shadow = 1;
+			break;
+		case 'y':
+			confirm = 1;
+			break;
+		default:
+			usage();
+		}
+	}
+	if (path == NULL)
+		usage();
+
+	/* load image */
+	fd = open(path, O_RDONLY);
+	if (fd == -1)
+		err(1, "open %s", path);
+	if (fstat(fd, &st) == -1)
+		err(1, "fstat %s", path);
+	if (st.st_size < (off_t)sr_bytes)
+		errx(1, "%s: image smaller than 64 KB shadow RAM",
path);
+	img = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+	if (img == MAP_FAILED)
+		err(1, "mmap %s", path);
+	close(fd);
+
+	/* validate image checksum */
+	stored_cs = nvm_word(img, NVM_W_SW_CHECKSUM);
+	expected_cs = nvm_compute_checksum(img);
+	if (stored_cs != expected_cs) {
+		errx(1, "%s: software checksum invalid (stored 0x%04x,
"
+		    "computed 0x%04x); refusing to apply",
+		    path, stored_cs, expected_cs);
+	}
+	devstart = nvm_word(img, NVM_W_DEV_STARTER_VERSION);
+	img_eetrack = (uint32_t)nvm_word(img, NVM_W_EETRACK_LO) |
+	    ((uint32_t)nvm_word(img, NVM_W_EETRACK_HI) << 16);
+
+	printf("image:      %s\n", path);
+	printf("  size:       %lld bytes\n", (long long)st.st_size);
+	printf("  firmware:   %x.%02x\n",
+	    (devstart >> 12) & 0xf, devstart & 0xff);
+	printf("  EETRACK ID: 0x%08x\n", img_eetrack);
+	printf("  checksum:   0x%04x [ok]\n", stored_cs);
+
+	/*
+	 * Read chip EETRACK ID for comparison, but only if we're
going
+	 * to write -- the chip may not exist for an offline dry-run.
+	 */
+	if (confirm) {
+		uint32_t chip_eetrack = chip_read_eetrack(s, ifname);
+
+		printf("chip:       %s\n", ifname);
+		printf("  EETRACK ID: 0x%08x", chip_eetrack);
+		if (chip_eetrack == img_eetrack)
+			printf(" (already at this image)\n");
+		else
+			printf(" (different)\n");
+	}
+
+	/*
+	 * Apply order:
+	 *   Phase 1: FLOW_NONAUTH modules (datasheet 3.4.5.4)
+	 *   Phase 2: FLOW_SHADOW modules (datasheet 3.4.5.3, batched)
+	 *   Phase 3: FLOW_AUTH modules (datasheet 3.4.5.5),
+	 *            EMP Image last because the chip stops servicing
the
+	 *            admin queue between its LAST_COMMAND and reboot.
+	 *
+	 * Modules with a 0xffff/0x0000 pointer in the image (or
absent
+	 * shadow-RAM data) are skipped rather than failing the apply
--
+	 * card-specific image variants typically leave slots empty.
+	 */
+	struct apply_step {
+		const char	*cli_name;
+		uint32_t	 src_byte;
+		uint32_t	 total_bytes;
+		const struct module_info *m;
+		int		 present;
+	};
+	struct apply_step steps[] = {
+		/* Phase 1: FLOW_NONAUTH */
+		{ "emp-global",    0, 0, NULL, 0 },
+		{ "manageability", 0, 0, NULL, 0 },
+		{ "emp-settings",  0, 0, NULL, 0 },
+		{ "phy-scripts",   0, 0, NULL, 0 },
+		{ "config-meta",   0, 0, NULL, 0 },
+		{ "ext-25g-phy",   0, 0, NULL, 0 },
+		/* Phase 3: FLOW_AUTH (emp-image last) */
+		{ "pcie-analog",   0, 0, NULL, 0 },
+		{ "phy-analog",    0, 0, NULL, 0 },
+		{ "option-rom",    0, 0, NULL, 0 },
+		{ "emp-image",     0, 0, NULL, 0 },
+	};
+	const size_t nonauth_n = 6;	/* indices 0..5 = Phase 1 */
+	size_t i, j, nsteps = nitems(steps);
+	struct shadow_step sst[nitems(shadow_module_table)];
+	size_t shadow_present;
+
+	/* resolve each step against the module_table[] and image */
+	for (i = 0; i < nsteps; i++) {
+		const struct module_info *m = NULL;
+		uint16_t ptr;
+
+		for (j = 0; j < nitems(module_table); j++) {
+			if (strcmp(steps[i].cli_name,
+			    module_table[j].cli_name) == 0) {
+				m = &module_table[j];
+				break;
+			}
+		}
+		if (m == NULL)
+			errx(1, "internal: module '%s' missing from
table",
+			    steps[i].cli_name);
+		steps[i].m = m;
+
+		ptr = nvm_word(img, m->update_ptr_word);
+		if (ptr == 0xffff || ptr == 0x0000) {
+			/* module not in this image -- skip */
+			continue;
+		}
+		if ((ptr & 0x8000) == 0) {
+			errx(1, "image word 0x%02x = 0x%04x: not an "
+			    "outside-shadow pointer for %s",
+			    m->update_ptr_word, ptr, m->display_name);
+		}
+		steps[i].src_byte = (uint32_t)(ptr & 0x7fff) * 4096;
+		steps[i].total_bytes = m->max_size_bytes;
+		if ((uint64_t)steps[i].src_byte + steps[i].total_bytes
>
+		    (uint64_t)st.st_size) {
+			errx(1, "%s would extend past image (need %u
bytes "
+			    "at 0x%x, image is %lld bytes)", m-
>display_name,
+			    steps[i].total_bytes, steps[i].src_byte,
+			    (long long)st.st_size);
+		}
+		steps[i].present = 1;
+	}
+
+	shadow_present = resolve_shadow_batch(img, sst, nitems(sst));
+
+	printf("\nplan: per-module update across three phases\n");
+	printf("\n  Phase 1: FLOW_NONAUTH (datasheet 3.4.5.4)\n");
+	for (i = 0; i < nonauth_n; i++) {
+		const struct module_info *m = steps[i].m;
+		size_t n = steps[i].total_bytes / 4096;
+
+		if (!steps[i].present) {
+			printf("    %-20s  (not in image, skipped)\n",
+			    m->display_name);
+			continue;
+		}
+		printf("    %-20s  src 0x%06x  %4zu sectors "
+		    "(update 0x%02x, erase 0x%02x)\n",
+		    m->display_name, steps[i].src_byte, n,
+		    m->update_ptr_word, m->erase_ptr_word);
+	}
+	printf("\n  Phase 2: FLOW_SHADOW (datasheet 3.4.5.3, batched)
"
+	    "[EXPERIMENTAL]\n");
+	if (!do_shadow) {
+		printf("    DISABLED (default).  -s enables it, but
the EMP\n");
+		printf("    regenerates these modules and direct
writes are\n");
+		printf("    fragile; the supported flow does not use -
s.\n");
+	} else {
+		for (i = 0; i < nitems(sst); i++) {
+			if (!sst[i].present) {
+				printf("    %-26s (not in image,
skipped)\n",
+				    sst[i].sm->display_name);
+				continue;
+			}
+			printf("    %-26s 0x%05x  %u bytes\n",
+			    sst[i].sm->display_name,
sst[i].byte_start,
+			    sst[i].byte_len);
+		}
+		if (shadow_present > 0)
+			printf("    + 1 checksum word write
[LAST]\n");
+	}
+	printf("\n  Phase 2b: NVM header version words (always
on)\n");
+	printf("    word 0x18 (DEV_STARTER_VERSION) <- image\n");
+	printf("    words 0x2d/0x2e (EETRACK ID)    <- image\n");
+	printf("    word 0x3f (software checksum)   <- recomputed
[LAST]\n");
+
+	printf("\n  Phase 3: FLOW_AUTH (datasheet 3.4.5.5)\n");
+	for (i = nonauth_n; i < nsteps; i++) {
+		const struct module_info *m = steps[i].m;
+		size_t n = steps[i].total_bytes / 4096;
+		int is_emp_last = (strcmp(steps[i].cli_name,
+		    "emp-image") == 0);
+
+		if (!steps[i].present) {
+			printf("    %-20s  (not in image, skipped)\n",
+			    m->display_name);
+			continue;
+		}
+		printf("    %-20s  src 0x%06x  %4zu sectors "
+		    "(update 0x%02x, erase 0x%02x)%s\n",
+		    m->display_name, steps[i].src_byte, n,
+		    m->update_ptr_word, m->erase_ptr_word,
+		    is_emp_last ? "  <- EMP last" : "");
+	}
+	printf("\n  FLOW_AUTH modules: chip verifies RSA-2048
signature on\n");
+	printf("    LAST_COMMAND; mismatch keeps the old module
active.\n");
+	printf("  FLOW_NONAUTH/FLOW_SHADOW: written without signature
check.\n");
+	printf("  reboot required after completion.\n");
+
+	if (!confirm) {
+		printf("\n*** dry run.  Re-run with -y to actually
apply.\n");
+		munmap(img, st.st_size);
+		return (0);
+	}
+
+	printf("\n*** writing chip NVM.  DO NOT INTERRUPT.\n");
+
+	nvm_open(s, ifname, IFNVM_ACCESS_WRITE);
+
+	/* Phase 1: FLOW_NONAUTH */
+	for (i = 0; i < nonauth_n; i++) {
+		if (!steps[i].present)
+			continue;
+		(void)apply_module(s, ifname, steps[i].m, img,
+		    steps[i].src_byte, steps[i].total_bytes);
+	}
+
+	/* Phase 2: FLOW_SHADOW (batched, opt-in via -s) */
+	if (do_shadow && shadow_present > 0)
+		apply_shadow_batch(s, ifname, img, sst, nitems(sst));
+
+	/* Phase 2b: NVM header version words (DEV_STARTER_VERSION,
+	 * EETRACK, checksum).  Always on -- pure metadata. */
+	apply_header_version(s, ifname, img);
+
+	/* Phase 3: FLOW_AUTH (EMP Image last) */
+	for (i = nonauth_n; i < nsteps; i++) {
+		if (!steps[i].present)
+			continue;
+		(void)apply_module(s, ifname, steps[i].m, img,
+		    steps[i].src_byte, steps[i].total_bytes);
+	}
+
+	/*
+	 * EMP Image was the final step.  The chip is now in the
+	 * "EMP swap pending" state and won't ack further AQ commands,
+	 * so nvm_close() may warn().  That's expected.
+	 */
+	nvm_close(s, ifname);
+	munmap(img, st.st_size);
+
+	printf("\nImage apply completed.  Reboot the system to load
the "
+	    "new firmware.\n");
+	return (0);
+}
+
+/*
+ * Issue an NVM_Erase AQ command via the kernel tunnel.  Datasheet
+ * 3.4.10.2 specifies that for NVM_Erase BOTH the length (bytes
+ * 18-19) AND the offset (bytes 20-23) are in 4 KB sector units --
+ * unlike NVM_Update, where the offset is in bytes.  Caller must
+ * hold an open NVM session.
+ */
+static int
+nvm_erase_chunk(int s, const char *ifname, uint8_t module_pointer,
+    uint32_t sector_index, uint16_t sector_count, uint8_t cmdflags,
+    int wait_arq, uint16_t timeout_ms)
+{
+	struct if_nvmcmd nc;
+
+	memset(&nc, 0, sizeof(nc));
+	if (strlcpy(nc.nc_ifname, ifname, sizeof(nc.nc_ifname)) >=
+	    sizeof(nc.nc_ifname))
+		errx(1, "interface name too long");
+	nc.nc_opcode = IXL_AQ_OP_NVM_ERASE;
+	nc.nc_module = module_pointer;
+	nc.nc_cmdflags = cmdflags;
+	nc.nc_offset = sector_index;
+	nc.nc_aqlen = sector_count;
+	nc.nc_buflen = 0;
+	nc.nc_buf = NULL;
+	if (wait_arq) {
+		nc.nc_flags = IFNVM_CMD_F_WAIT_ARQ;
+		nc.nc_timeout_ms = timeout_ms;
+	}
+
+	if (ioctl(s, SIOCSIFNVMCMD, &nc) == -1)
+		err(1, "%s: NVM_ERASE module=%02x sector=%u", ifname,
+		    module_pointer, sector_index);
+	return (nc.nc_retval);
+}
+
+/*
+ * Update one of the authenticated outside-shadow modules: Option ROM,
+ * EMP Image, PCIe Analog, or PHY Analog (datasheet 3.4.5.5).
+ *
+ * The chip verifies the module's RSA-2048 signature before swapping
+ * pointers; signing is Intel's job, we just push the bytes.  Per the
+ * datasheet, the entire module area (1160 KB for OROM/EMP image,
+ * 8 KB for the analog modules) must always be written, sector by
+ * sector, with each sector erased immediately before its write.
+ */
+static int
+cmd_module_update(int s, const char *ifname, int argc, char **argv)
+{
+	const char *path = NULL;
+	const char *modname = NULL;
+	const struct module_info *m = NULL;
+	int confirm = 0, ch, fd;
+	struct stat st;
+	uint8_t *img;
+	uint16_t ptr;
+	uint32_t src_byte, total_bytes;
+	size_t i, n_sectors;
+
+	optreset = 1;
+	optind = 1;
+	while ((ch = getopt(argc, argv, "m:f:y")) != -1) {
+		switch (ch) {
+		case 'm':
+			modname = optarg;
+			break;
+		case 'f':
+			path = optarg;
+			break;
+		case 'y':
+			confirm = 1;
+			break;
+		default:
+			usage();
+		}
+	}
+	if (path == NULL || modname == NULL)
+		usage();
+
+	/* Dispatch to the shadow-RAM update flow if the module name
is
+	 * a shadow-RAM module (datasheet 3.4.5.3). */
+	for (i = 0; i < nitems(shadow_module_table); i++) {
+		if (strcmp(modname, shadow_module_table[i].cli_name)
== 0)
+			return (cmd_shadow_update_single(s, ifname,
+			    &shadow_module_table[i], path, confirm));
+	}
+
+	for (i = 0; i < nitems(module_table); i++) {
+		if (strcmp(modname, module_table[i].cli_name) == 0) {
+			m = &module_table[i];
+			break;
+		}
+	}
+	if (m == NULL)
+		errx(1, "module '%s' is not supported "
+		    "(try: option-rom, emp-image, pcie-analog, phy-
analog, "
+		    "emp-global, manageability, emp-settings, phy-
scripts, "
+		    "config-meta, ext-25g-phy, "
+		    "auto-gen-ptrs, pcir-autoload, por-autoload, "
+		    "globr-autoload, corer-autoload, emp-sr, feature-
cfg, "
+		    "core-mem, immediate)",
+		    modname);
+
+	/* load image */
+	fd = open(path, O_RDONLY);
+	if (fd == -1)
+		err(1, "open %s", path);
+	if (fstat(fd, &st) == -1)
+		err(1, "fstat %s", path);
+	img = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+	if (img == MAP_FAILED)
+		err(1, "mmap %s", path);
+	close(fd);
+
+	/* locate the source module in the image */
+	ptr = nvm_word(img, m->update_ptr_word);
+	if (ptr == 0xffff || ptr == 0x0000)
+		errx(1, "%s is not present in this image "
+		    "(word 0x%02x = 0x%04x); the image likely targets
a "
+		    "different card variant", m->display_name,
+		    m->update_ptr_word, ptr);
+	if ((ptr & 0x8000) == 0)
+		errx(1, "image word 0x%02x = 0x%04x: not an outside-
shadow "
+		    "pointer for %s", m->update_ptr_word, ptr,
+		    m->display_name);
+
+	src_byte = (uint32_t)(ptr & 0x7fff) * 4096;
+	total_bytes = m->max_size_bytes;
+	if ((uint64_t)src_byte + total_bytes > (uint64_t)st.st_size)
+		errx(1, "%s would extend past image (need %u bytes at
0x%x, "
+		    "image is %lld bytes)", m->display_name,
total_bytes,
+		    src_byte, (long long)st.st_size);
+	n_sectors = total_bytes / 4096;
+
+	printf("%s update plan:\n", m->display_name);
+	printf("  source:        %s offset 0x%x (%u KB)\n",
+	    path, src_byte, total_bytes / 1024);
+	printf("  Update target: word 0x%02x (module pointer)\n",
+	    m->update_ptr_word);
+	printf("  Erase target:  word 0x%02x (free provisioning
area)\n",
+	    m->erase_ptr_word);
+	printf("  sectors:       %zu x 4 KB\n", n_sectors);
+	printf("  commands:      %zu NVM_Erase + %zu NVM_Update (final
has "
+	    "LAST_COMMAND)\n", n_sectors, n_sectors);
+	printf("  flow:          datasheet 3.4.5.5 (authenticated
module "
+	    "outside shadow RAM)\n");
+	printf("  chip will verify RSA-2048 signature; a mismatch
causes\n");
+	printf("  the chip to reject the update and the old module
stays\n");
+	printf("  active.\n");
+
+	if (!confirm) {
+		printf("\n*** dry run.  Re-run with -y to actually
apply.\n");
+		munmap(img, st.st_size);
+		return (0);
+	}
+
+	printf("\n*** writing chip NVM.  DO NOT INTERRUPT.\n");
+
+	nvm_open(s, ifname, IFNVM_ACCESS_WRITE);
+	(void)apply_module(s, ifname, m, img, src_byte, total_bytes);
+	nvm_close(s, ifname);
+	munmap(img, st.st_size);
+
+	printf("\n%s update completed.\n", m->display_name);
+	printf("Reboot the system to load the new module.\n");
+	return (0);
+}
+
+/*
+ * Per-sector erase+update loop for one authenticated outside-shadow
+ * module (datasheet 3.4.5.5).  Caller has already opened the NVM
+ * session and validated that src_byte..src_byte+total_bytes is in
+ * range.  Each NVM_Erase and NVM_Update is async (datasheet 3.4.10.2
/
+ * 3.4.10.3) so every command waits for the ARQ completion event.
+ * On any chip-side failure this calls errx() -- callers that need to
+ * release the NVM session before exiting must do so via atexit or
+ * accept that the kernel will reap it when the process dies.
+ */
+static int
+apply_module(int s, const char *ifname, const struct module_info *m,
+    const uint8_t *img, uint32_t src_byte, uint32_t total_bytes)
+{
+	uint32_t i, n_sectors = total_bytes / 4096;
+
+	for (i = 0; i < n_sectors; i++) {
+		uint32_t off = i * 4096;
+		int is_last = (i + 1 == n_sectors);
+		int retval;
+
+		fprintf(stderr, "  %s: sector %4u/%u  erase\r",
+		    m->display_name, i + 1, n_sectors);
+		fflush(stderr);
+		retval = nvm_erase_chunk(s, ifname, m->erase_ptr_word,
+		    i, 1, 0, 1 /* wait_arq */, 5000);
+		if (retval != 0) {
+			fprintf(stderr, "\n");
+			errx(1, "%s: erase sector %u: AQ
retval=0x%04x",
+			    m->display_name, i, retval);
+		}
+
+		fprintf(stderr, "  %s: sector %4u/%u  write%s\r",
+		    m->display_name, i + 1, n_sectors,
+		    is_last ? " [LAST]" : "      ");
+		fflush(stderr);
+		retval = nvm_update_chunk(s, ifname, m-
>update_ptr_word, off,
+		    4096,
+		    is_last ? IXL_AQ_NVM_LAST_COMMAND : 0,
+		    img + src_byte + off, 1 /* wait_arq */,
+		    is_last ? 60000 : 5000);
+		if (retval != 0) {
+			fprintf(stderr, "\n");
+			errx(1, "%s: update sector %u: AQ
retval=0x%04x",
+			    m->display_name, i, retval);
+		}
+	}
+	fprintf(stderr, "\n");
+	return (0);
+}
+
+/*
+ * Find a shadow-RAM module's byte location and length given its
+ * pointer-word index and a 64-KB shadow buffer.  The pointer word at
+ * shadow[pointer_word] holds the module's word offset within shadow
+ * RAM (bit 15 must be clear -- bit 15 set means outside-shadow,
+ * sector units).  The first word at that location encodes the module
+ * length in words exclusive of itself (datasheet 6.1.5.1 Table 6-4),
+ * so the total module size in bytes is (length_word + 1) * 2.
+ *
+ * Returns 0 on success.  Returns 1 if the module is absent (pointer
+ * 0xffff or 0x0000).  Calls errx() on malformed/out-of-bounds.
+ */
+static int
+resolve_shadow_module(const uint8_t *shadow, uint16_t pointer_word,
+    const char *display_name, uint32_t *byte_start, uint32_t
*byte_len)
+{
+	uint16_t ptr = nvm_word(shadow, pointer_word);
+	uint16_t len_words;
+	uint32_t start, len_bytes;
+
+	if (ptr == 0xffff || ptr == 0x0000)
+		return (1);	/* absent */
+	if (ptr & 0x8000) {
+		errx(1, "%s: pointer 0x%04x at word 0x%02x has bit 15
set "
+		    "(outside-shadow sector pointer, not a shadow
module)",
+		    display_name, ptr, pointer_word);
+	}
+	start = (uint32_t)ptr * 2;
+	if (start + 2 > NVM_SR_SIZE_WORDS * 2) {
+		errx(1, "%s: pointer 0x%04x maps to byte 0x%x, beyond
"
+		    "shadow RAM", display_name, ptr, start);
+	}
+	len_words = nvm_word(shadow, ptr);
+	if (len_words == 0xffff || len_words == 0) {
+		/*
+		 * Pointer slot is filled, but the module's length
word is
+		 * the uninitialised-flash value (0xffff) or zero --
the
+		 * module slot is reserved but not populated.  Treat
as
+		 * absent so callers can skip it.
+		 */
+		return (1);
+	}
+	len_bytes = ((uint32_t)len_words + 1) * 2;
+	if (start + len_bytes > NVM_SR_SIZE_WORDS * 2) {
+		errx(1, "%s: module at 0x%x length %u bytes extends
past "
+		    "shadow RAM (max 0x%x)", display_name, start,
len_bytes,
+		    NVM_SR_SIZE_WORDS * 2);
+	}
+	*byte_start = start;
+	*byte_len = len_bytes;
+	return (0);
+}
+
+/*
+ * Write a shadow-RAM byte region to the chip in chunks of up to
+ * IXL_NVM_CHUNK (4 KB) bytes, using NVM_Update with module_pointer=0
+ * (datasheet 3.4.5.3).  No NVM_Erase is needed -- the chip stages
+ * shadow writes in the inactive bank and commits on LAST_COMMAND.
+ *
+ * A single shadow NVM_Update command must not cross a 4 KB page
+ * boundary: the chip processes shadow writes per 4 KB page and
returns
+ * AQ retval 0x000e (EINVAL) for a command that spans two pages (this
+ * is not documented in the datasheet, found empirically).  So each
+ * chunk is clipped to the next absolute 4 KB boundary of the shadow
+ * RAM, NOT chunked relative to byte_start.  The start offset itself
+ * need not be aligned.
+ *
+ * The cmdflags arg is applied only to the FINAL chunk (so callers
+ * batching multiple regions can pass 0 here for all but the last,
+ * and IXL_AQ_NVM_LAST_COMMAND for the very last write of the
session).
+ * Calls errx() on chip-side failure.
+ */
+static void
+write_shadow_region(int s, const char *ifname, const uint8_t *buf,
+    uint32_t byte_start, uint32_t byte_len, uint8_t final_cmdflags)
+{
+	uint32_t off = byte_start;
+	uint32_t end = byte_start + byte_len;
+
+	while (off < end) {
+		uint32_t page_end = (off + IXL_NVM_CHUNK) &
~(IXL_NVM_CHUNK - 1);
+		uint32_t chunk_end = (end < page_end) ? end :
page_end;
+		uint16_t len = (uint16_t)(chunk_end - off);
+		int is_final = (chunk_end >= end);
+		uint8_t flags = is_final ? final_cmdflags : 0;
+		uint16_t to_ms = (flags & IXL_AQ_NVM_LAST_COMMAND) ?
+		    60000 : 5000;
+		int retval;
+
+		retval = nvm_update_chunk(s, ifname, 0 /* shadow-RAM
*/,
+		    off, len, flags, buf + off, 1 /* wait_arq */,
to_ms);
+		if (retval != 0) {
+			errx(1, "shadow write at 0x%x: AQ
retval=0x%04x",
+			    off, retval);
+		}
+		off = chunk_end;
+	}
+}
+
+/*
+ * Update a single shadow-RAM module on the chip from an image file.
+ * Datasheet 3.4.5.3.  Read chip's current 64 KB shadow, overlay the
+ * image's bytes for this module, recompute the software checksum,
+ * write the module region (non-LAST) and the checksum word (LAST).
+ */
+static int
+cmd_shadow_update_single(int s, const char *ifname,
+    const struct shadow_module_info *sm, const char *path, int
confirm)
+{
+	const size_t sr_bytes = NVM_SR_SIZE_WORDS * sizeof(uint16_t);
+	int fd;
+	struct stat st;
+	uint8_t *img;
+	uint8_t shadow[NVM_SR_SIZE_WORDS * 2];
+	uint32_t img_start = 0, img_len = 0;
+	uint16_t new_cksum;
+	int absent;
+
+	/* load image */
+	fd = open(path, O_RDONLY);
+	if (fd == -1)
+		err(1, "open %s", path);
+	if (fstat(fd, &st) == -1)
+		err(1, "fstat %s", path);
+	if (st.st_size < (off_t)sr_bytes)
+		errx(1, "%s: image smaller than 64 KB shadow RAM",
path);
+	img = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+	if (img == MAP_FAILED)
+		err(1, "mmap %s", path);
+	close(fd);
+
+	absent = resolve_shadow_module(img, sm->pointer_word, sm-
>display_name,
+	    &img_start, &img_len);
+	if (absent) {
+		uint16_t p = nvm_word(img, sm->pointer_word);
+		uint32_t off = (uint32_t)(p & 0x7fff) * 2;
+		uint16_t lw = (p != 0 && p != 0xffff && (p & 0x8000)
== 0) ?
+		    nvm_word(img, p) : 0xffff;
+		errx(1, "%s is not present in this image "
+		    "(pointer word 0x%02x = 0x%04x; length word at "
+		    "byte 0x%x = 0x%04x)",
+		    sm->display_name, sm->pointer_word, p, off, lw);
+	}
+
+	printf("%s update plan:\n", sm->display_name);
+	printf("  source:       %s\n", path);
+	printf("  image bytes:  0x%05x-0x%05x (%u bytes)\n",
+	    img_start, img_start + img_len - 1, img_len);
+	printf("  pointer word: 0x%02x (shadow-RAM word units)\n",
+	    sm->pointer_word);
+	printf("  target:       shadow RAM byte 0x%x, %u bytes\n",
+	    img_start, img_len);
+	printf("  flow:         datasheet 3.4.5.3 (shadow-RAM
module)\n");
+	printf("  commands:     %u NVM_Update + 1 checksum write
[LAST]\n",
+	    (img_len + IXL_NVM_CHUNK - 1) / IXL_NVM_CHUNK);
+	printf("  no NVM_Erase; word 0x3f (checksum) is
recomputed\n");
+
+	if (!confirm) {
+		printf("\n*** dry run.  Re-run with -y to actually
apply.\n");
+		munmap(img, st.st_size);
+		return (0);
+	}
+
+	printf("\n*** writing chip NVM.  DO NOT INTERRUPT.\n");
+
+	nvm_open(s, ifname, IFNVM_ACCESS_WRITE);
+	nvm_read_full(s, ifname, 0, sizeof(shadow), shadow, "reading
shadow");
+	fprintf(stderr, "\n");
+
+	/* overlay the image's module bytes onto the chip shadow
buffer */
+	memcpy(shadow + img_start, img + img_start, img_len);
+
+	/* recompute software checksum on the new state */
+	new_cksum = nvm_compute_checksum(shadow);
+	shadow[NVM_W_SW_CHECKSUM * 2] = (uint8_t)(new_cksum & 0xff);
+	shadow[NVM_W_SW_CHECKSUM * 2 + 1] = (uint8_t)(new_cksum >> 8);
+
+	fprintf(stderr, "  writing %s region (0x%x, %u bytes)\n",
+	    sm->display_name, img_start, img_len);
+	write_shadow_region(s, ifname, shadow, img_start, img_len, 0);
+
+	fprintf(stderr, "  writing checksum 0x%04x at word 0x%02x
[LAST]\n",
+	    new_cksum, NVM_W_SW_CHECKSUM);
+	write_shadow_region(s, ifname, shadow,
+	    NVM_W_SW_CHECKSUM * 2, 2, IXL_AQ_NVM_LAST_COMMAND);
+
+	nvm_close(s, ifname);
+	munmap(img, st.st_size);
+
+	printf("\n%s update completed.\n", sm->display_name);
+	printf("Reboot the system to load the new module.\n");
+	return (0);
+}
+
+/*
+ * Resolve every shadow_module_table[] entry against the image,
filling
+ * in byte_start/byte_len/present.  Returns the number of populated
+ * modules.  Pure resolution, no chip access.
+ */
+static size_t
+resolve_shadow_batch(const uint8_t *img, struct shadow_step *sst,
+    size_t n)
+{
+	size_t i, present = 0;
+
+	for (i = 0; i < n; i++) {
+		sst[i].sm = &shadow_module_table[i];
+		sst[i].byte_start = 0;
+		sst[i].byte_len = 0;
+		sst[i].present = (resolve_shadow_module(img,
+		    shadow_module_table[i].pointer_word,
+		    shadow_module_table[i].display_name,
+		    &sst[i].byte_start, &sst[i].byte_len) == 0);
+		if (sst[i].present)
+			present++;
+	}
+	return (present);
+}
+
+/*
+ * Apply all populated shadow-RAM modules in one batched NVM_Update
+ * sequence (datasheet 3.4.5.3): read chip's current shadow, overlay
+ * each present module's bytes from the image, recompute the software
+ * checksum, write each region and finally the checksum word with
+ * LAST_COMMAND.  Caller must already hold an open NVM session.
+ */
+static void
+apply_shadow_batch(int s, const char *ifname, const uint8_t *img,
+    struct shadow_step *sst, size_t n)
+{
+	uint8_t shadow[NVM_SR_SIZE_WORDS * 2];
+	size_t i, written = 0;
+	uint16_t new_cksum;
+
+	for (i = 0; i < n; i++) {
+		if (sst[i].present)
+			written++;
+	}
+	if (written == 0) {
+		fprintf(stderr, "  no shadow modules populated in
image\n");
+		return;
+	}
+
+	nvm_read_full(s, ifname, 0, sizeof(shadow), shadow,
+	    "reading shadow");
+	fprintf(stderr, "\n");
+
+	for (i = 0; i < n; i++) {
+		if (!sst[i].present)
+			continue;
+		memcpy(shadow + sst[i].byte_start,
+		    img + sst[i].byte_start, sst[i].byte_len);
+	}
+
+	new_cksum = nvm_compute_checksum(shadow);
+	shadow[NVM_W_SW_CHECKSUM * 2] = (uint8_t)(new_cksum & 0xff);
+	shadow[NVM_W_SW_CHECKSUM * 2 + 1] = (uint8_t)(new_cksum >> 8);
+
+	for (i = 0; i < n; i++) {
+		if (!sst[i].present)
+			continue;
+		fprintf(stderr, "  shadow: %-26s 0x%05x  %u bytes\n",
+		    sst[i].sm->display_name, sst[i].byte_start,
+		    sst[i].byte_len);
+		write_shadow_region(s, ifname, shadow,
+		    sst[i].byte_start, sst[i].byte_len, 0);
+	}
+	fprintf(stderr, "  shadow: %-26s 0x%05x  2 bytes [LAST]\n",
+	    "checksum word 0x3f", NVM_W_SW_CHECKSUM * 2);
+	write_shadow_region(s, ifname, shadow,
+	    NVM_W_SW_CHECKSUM * 2, 2, IXL_AQ_NVM_LAST_COMMAND);
+}
+
+/*
+ * Update the NVM header version metadata to match the new image:
+ *   word 0x18  DEV_STARTER_VERSION    (e.g. 0x9055 = "9.55")
+ *   words 0x2d-0x2e  EETRACK_LO/HI    (canonical match key for cfg)
+ * Then recompute and write the software checksum at word 0x3f with
+ * LAST_COMMAND.  These are pure metadata fields -- not card identity,
+ * not chip-managed -- so it is safe to overwrite from the image.
+ *
+ * Without this step the chip's running EMP is upgraded (FLOW_AUTH
+ * swaps the EMP image, dmesg's "FW" reflects the new build) but the
+ * NVM header still labels the chip as the previous image version,
+ * which makes the next scan show a mismatched nvm/fw pairing and the
+ * nvmupdate.cfg match against the old EETRACK ID.
+ */
+static void
+apply_header_version(int s, const char *ifname, const uint8_t *img)
+{
+	uint8_t shadow[NVM_SR_SIZE_WORDS * 2];
+	uint16_t new_cksum;
+
+	nvm_read_full(s, ifname, 0, sizeof(shadow), shadow,
+	    "reading shadow");
+	fprintf(stderr, "\n");
+
+	memcpy(shadow + NVM_W_DEV_STARTER_VERSION * 2,
+	    img + NVM_W_DEV_STARTER_VERSION * 2, 2);
+	memcpy(shadow + NVM_W_EETRACK_LO * 2,
+	    img + NVM_W_EETRACK_LO * 2, 4);
+
+	new_cksum = nvm_compute_checksum(shadow);
+	shadow[NVM_W_SW_CHECKSUM * 2] = (uint8_t)(new_cksum & 0xff);
+	shadow[NVM_W_SW_CHECKSUM * 2 + 1] = (uint8_t)(new_cksum >> 8);
+
+	fprintf(stderr, "  header: nvm version 0x%04x (word 0x18)\n",
+	    nvm_word(shadow, NVM_W_DEV_STARTER_VERSION));
+	write_shadow_region(s, ifname, shadow,
+	    NVM_W_DEV_STARTER_VERSION * 2, 2, 0);
+
+	fprintf(stderr, "  header: EETRACK 0x%08x (words
0x2d/0x2e)\n",
+	    (uint32_t)nvm_word(shadow, NVM_W_EETRACK_LO) |
+	    ((uint32_t)nvm_word(shadow, NVM_W_EETRACK_HI) << 16));
+	write_shadow_region(s, ifname, shadow,
+	    NVM_W_EETRACK_LO * 2, 4, 0);
+
+	fprintf(stderr, "  header: checksum 0x%04x at word 0x3f
[LAST]\n",
+	    new_cksum);
+	write_shadow_region(s, ifname, shadow,
+	    NVM_W_SW_CHECKSUM * 2, 2, IXL_AQ_NVM_LAST_COMMAND);
+}