Adding upstream version 2.8.upstream/2.8

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

1 files changed, 162 insertions, 0 deletions

diff --git a/Documentation/nvme-fw-commit.1 b/Documentation/nvme-fw-commit.1
new file mode 100644
index 0000000..62e46ee
--- /dev/null
+++ b/Documentation/nvme-fw-commit.1
@@ -0,0 +1,162 @@
+'\" t
+.\"     Title: nvme-fw-commit
+.\"    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\-COMMIT" "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-commit \- Used to verify and commit a firmware image\&.
+.SH "SYNOPSIS"
+.sp
+.nf
+\fInvme fw\-commit\fR <device> [\-\-slot=<slot> | \-s <slot>]
+                        [\-\-action=<action> | \-a <action>]
+                        [\-\-bpid=<boot\-partid> | \-b <boot\-partid>]
+                        [\-\-output\-format=<fmt> | \-o <fmt>] [\-\-verbose | \-v]
+.fi
+.SH "DESCRIPTION"
+.sp
+For the NVMe device given, send an nvme Firmware Commit admin command and provides the results\&.
+.sp
+The Firmware Commit command is used to verify that a valid firmware image has been downloaded and to commit that revision to a specific firmware slot\&. The host may select the firmware image to commit on the next controller reset (CC\&.EN transitions from \(oq1\(cq to \(oq0\(cq, a PCI function level reset, and/or other Controller or NVM Subsystem Reset) as part of this command\&. The currently executing firmware revision may be determined from the Firmware Revision field of the Identify Controller data structure as indicated in the Firmware Slot Information log page\&.
+.sp
+No further action is automatically taken to reset the device, which is usually required to complete the activation process\&. If your kernel and driver are recent enough, you can commit the firmware by issuing a reset through Linux sysfs, for example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+ # echo 1 > /sys/class/nvme/nvme0/device/reset
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+If your kernel is not recent enough, you will need to remove and add the device some other way\&.
+.SH "OPTIONS"
+.PP
+\-a <action>, \-\-action=<action>
+.RS 4
+Commit Action: This field specifies the action that is taken on the image downloaded with the Firmware Image Download command or on a previously downloaded and placed image\&.
+.TS
+allbox tab(:);
+lt lt
+lt lt
+lt lt
+lt lt
+lt lt
+lt lt
+lt lt.
+T{
+Value
+T}:T{
+Definition
+T}
+T{
+0
+T}:T{
+Downloaded image replaces the image indicated by the Firmware Slot field\&. This image is not activated\&.
+T}
+T{
+1
+T}:T{
+Downloaded image replaces the image indicated by the Firmware Slot field\&. This image is activated at the next reset\&.
+T}
+T{
+2
+T}:T{
+The image indicated by the Firmware Slot field is activated at the next reset\&.
+T}
+T{
+3
+T}:T{
+The image specified by the Firmware Slot field is requested to be activated immediately without reset\&.
+T}
+T{
+6
+T}:T{
+Downloaded image replaces the Boot Partition specified by the Boot Partition ID field\&.
+T}
+T{
+7
+T}:T{
+Mark the Boot Partition specified in the BPID field as active and update BPINFO\&.ABPID\&.
+T}
+.TE
+.sp 1
+.RE
+.PP
+\-s <slot>, \-\-slot=<slot>
+.RS 4
+Firmware Slot: Specifies the firmware slot that shall be used for the Commit Action, if applicable\&. If the value specified is 0h, then the controller shall choose the firmware slot (slot 1 \(en 7) to use for the operation\&.
+.RE
+.PP
+\-\-bpid=<boot\-partid>, \-b <boot\-partid>
+.RS 4
+Specifies the Boot partition that shall be used for the Commit Action, if applicable (default: 0)
+.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
+.\}
+commit the last downloaded fw to slot 1\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# nvme fw\-commit /dev/nvme0 \-\-slot=1 \-\-action=2
+.fi
+.if n \{\
+.RE
+.\}
+.RE
+.SH "ALIAS"
+.sp
+fw\-activate
+.SH "NVME"
+.sp
+Part of the nvme\-user suite