NVME-FW-DOWNLOAD(1)

📦
version 3.2 · 14 versions
, in arch rolling

💾 nvme-fw-download — like, the NVMe Manual, but make it make sense ✨

okay bestie, listen up 👑 this is a page from the NVMe Manual and it's all about nvme-fw-download, aka how you shove a firmware image at your controller. it's giving "glow-up for your SSD" energy and honestly? kind of iconic. let's get into it 💅

🌸 NAME 🌸

nvme-fw-download — download all of a firmware image, or just a lil portion of it, to an NVMe thing. 🎀

🦋 SYNOPSIS 🦋

nvme [<global-options>] fw download <device>
                        [--fw=<firmware-file> | -f <firmware-file>]
                        [--xfer=<transfer-size> | -x <transfer-size>]
                        [--offset=<offset> | -O <offset>]
                        [--stream]

no cap, that's the whole vibe up there ⬆️

💖 DESCRIPTION 💖

so the Firmware Image Download command is literally the thing that downloads all of a firmware image (or just a piece of it) for a future update to the controller. key word: future. it's not doing the update now, it's just getting the goods in place. 🧳

and the bestie behavior here? this command can be submitted while other commands on the Admin Submission Queue or I/O Submission Queues are still outstanding. it does not care, it's a multitasker. it just copies the new firmware image — in whole or in part — to the controller. main character energy fr fr. ⭐

your firmware image can be built out of multiple pieces, each one downloaded with its own separate Firmware Image Download command. every single one of these commands includes a Dword Offset and a Number of Dwords that specify a Dword range. and here's the rule, no exceptions: host software shall make sure firmware pieces do not have Dword ranges that overlap. 🚨 overlapping = bad vibes. that said, firmware portions may be submitted out of order to the controller, so you're not locked into a strict sequence. 🙈

okay and super important: the new firmware image is not applied as part of the Firmware Image Download command. nope. it gets applied after a reset, where the image to apply and the firmware slot it should be committed to is specified with the Firmware Commit command — that's nvme fw-commit <args>. so like, download now, commit later, reset somewhere in there. iykyk 💫

note note note 🫶 nvme-cli has to allocate a contiguous (linear) memory buffer and map the firmware binary into it. to do that, nvme-cli first tries to allocate the buffer using huge TLB pages. if allocating with huge pages fails, it falls back to posix_memalign() combined with madvise(). and if the kernel rejects the huge page advice, nvme-cli keeps the aligned buffer and lets the I/O path attempt to map it. so it always has a backup plan, she's resilient. 💪

the optional --stream mode avoids allocating a buffer for the complete firmware image entirely. instead it reads and downloads one transfer-sized portion at a time. lowkey the memory-efficient queen. 🌈

and if you want to increase the likelihood of success (manifesting ✨), you may want to pre-allocate a number of huge pages before you start the firmware download:

echo 20 > /proc/sys/vm/nr_hugepages

for more details, refer to: https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt

🚨 deprecation warning, bestie, pay attention 🚨 the bare nvme fw-download form (without a space) still works as a deprecated alias and will be removed in a future major version. new scripts should use nvme fw download instead. okay so like, the old way still slays but it's on its way out — write the new one. periodt. 💀

✨ OPTIONS ✨

  • -f <firmware-file>, --fw=<firmware-file> — required argument, no skips allowed. this specifies the path to the device's firmware file on your system that will be read by the program and sent to the device. like, the actual file, the whole point of the operation. 🍓
  • -x <transfer-size>, --xfer=<transfer-size> — specifies the size to split each transfer. super useful if the device has a max transfer size requirement for firmware. it defaults to 4k. 🎀
  • -O <offset>, --offset=<offset> — specifies the starting offset in dwords. this is really only useful if your firmware is split across multiple files; otherwise the offset starts at zero and automatically adjusts based on the xfer size you gave. so like, only touch this if you know why you're touching it. 💅
  • --stream — read and download one transfer-sized portion of the firmware image at a time instead of mapping the complete image into memory. this avoids the huge page requirement and limits memory use to the transfer size. obsessed. 🦋

🌟 GLOBAL OPTIONS 🌟

these options are defined at the top-level nvme command and are available to this subcommand too. so they're the big-sister options, but they still got you. 🫶

  • --dry-run — print the command that would be executed, but do not actually execute it. dress rehearsal only. 🎭
  • --no-ioctl-probing — disable probing for 64-bit IOCTL support. 🧚
  • --no-retries — disable retry logic on transient errors. one shot, one opportunity. 💀
  • -o <fmt>, --output-format=<fmt> — set the reporting format to normal, tabular, 'json, or binary. only one output format may be used at a time, pick a lane bestie. 🌸
  • --output-format-version=<version> — select the output format version. version 1 uses the original field naming, while version 2 (the default) provides more consistent and script-friendly field names. other versions are rejected. 🚫
  • --quiet — suppress informational messages. errors are still reported, and --quiet cancels any --verbose for the library log level. she's quiet but she's still honest. 🤫
  • --set-options=<key=value>[,<key=value>...] — set libnvme library options for this invocation. supported keys are force-4k, mi-probe-enabled, test-base-dir and test-sysfs-dir. 🎛️
  • --timeout=<ms> — set the timeout for the command in milliseconds. infinite or -1 waits without a time limit (0xffffffff). no clock, no stress. ⏳
  • -v, --verbose — increase the level of detail in the output. may be specified multiple times to further increase verbosity. the more the merrier honestly. 🔥

these options can also be set as machine-wide defaults in nvme-cli.conf(5). a command-line flag always overrides the file. always. 👑

🌈 EXAMPLES 🌈

  • transfer a firmware size 128KiB at a time:
# nvme fw download /dev/nvme0 --fw=/path/to/nvme.fw --xfer=0x20000
  • read and download a firmware image one transfer-sized portion at a time:
# nvme fw download /dev/nvme0 --fw=/path/to/nvme.fw --stream

💜 NVME 💜

part of the nvme-user suite. family. 💖

and that's the page, bestie 🎀 go forth and flash responsibly — this was NVMe material dated 10/30/2026, signing off with so much love 🫶✨💅

📦 where this page comes from