Index | Thread | Search

From:
Stefan Huber <stefan.huber@stusta.de>
Subject:
Re: 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 14:18:53 +0100

Download raw body.

Thread
Again, sorry about the line break.



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);
+}