Adding upstream version 2.8.upstream/2.8

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 103 insertions, 0 deletions

diff --git a/Documentation/nvme-fw-download.1 b/Documentation/nvme-fw-download.1
new file mode 100644
index 0000000..18a87ca
--- /dev/null
+++ b/Documentation/nvme-fw-download.1
@@ -0,0 +1,103 @@
+'\" t
+.\"     Title: nvme-fw-download
+.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 02/14/2024
+.\"    Manual: NVMe Manual
+.\"    Source: NVMe
+.\"  Language: English
+.\"
+.TH "NVME\-FW\-DOWNLOAD" "1" "02/14/2024" "NVMe" "NVMe Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+nvme-fw-download \- Download all or a portion of an nvme firmware image\&.
+.SH "SYNOPSIS"
+.sp
+.nf
+\fInvme fw\-download\fR <device> [\-\-fw=<firmware\-file> | \-f <firmware\-file>]
+                        [\-\-xfer=<transfer\-size> | \-x <transfer\-size>]
+                        [\-\-offset=<offset> | \-O <offset>]
+                        [\-\-output\-format=<fmt> | \-o <fmt>] [\-\-verbose | \-v]
+.fi
+.SH "DESCRIPTION"
+.sp
+The Firmware Image Download command is used to download all or a portion of the firmware image for a future update to the controller\&. The Firmware Image Download command may be submitted while other commands on the Admin Submission Queue or I/O Submission Queues are outstanding\&. The Firmware Image Download command copies the new firmware image (in whole or in part) to the controller\&.
+.sp
+The firmware image may be constructed of multiple pieces that are individually downloaded with separate Firmware Image Download commands\&. Each Firmware Image Download command includes a Dword Offset and Number of Dwords that specify a Dword range\&. The host software shall ensure that firmware pieces do not have Dword ranges that overlap\&. Firmware portions may be submitted out of order to the controller\&.
+.sp
+The new firmware image is not applied as part of the Firmware Image Download command\&. It is applied following a reset, where the image to apply and the firmware slot it should be committed to is specified with the Firmware Commit command (nvme fw\-commit <args>)\&.
+.SH "OPTIONS"
+.PP
+\-f <firmware\-file>, \-\-fw=<firmware\-file>
+.RS 4
+Required argument\&. This specifies the path to the device\(cqs firmware file on your system that will be read by the program and sent to the device\&.
+.RE
+.PP
+\-x <transfer\-size>, \-\-xfer=<transfer\-size>
+.RS 4
+This specifies the size to split each transfer\&. This is useful if the device has a max transfer size requirement for firmware\&. It defaults to 4k\&.
+.RE
+.PP
+\-O <offset>, \-\-offset=<offset>
+.RS 4
+This specifies the starting offset in dwords\&. This is really only useful if your firmware is split in multiple files; otherwise the offset starts at zero and automatically adjusts based on the
+\fIxfer\fR
+size given\&.
+.RE
+.PP
+\-o <fmt>, \-\-output\-format=<fmt>
+.RS 4
+Set the reporting format to
+\fInormal\fR,
+\fIjson\fR
+or
+\fIbinary\fR\&. Only one output format can be used at a time\&.
+.RE
+.PP
+\-v, \-\-verbose
+.RS 4
+Increase the information detail in the output\&.
+.RE
+.SH "EXAMPLES"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Transfer a firmware size 128KiB at a time:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# nvme fw\-download /dev/nvme0 \-\-fw=/path/to/nvme\&.fw \-\-xfer=0x20000
+.fi
+.if n \{\
+.RE
+.\}
+.RE
+.SH "NVME"
+.sp
+Part of the nvme\-user suite