From: Keith Busch <keith.busch@intel.com>
Date: Tue, 19 Dec 2017 20:33:49 +0000 (-0700)
Subject: Update documentation to use aliases
X-Git-Tag: v1.5~3
X-Git-Url: https://www.infradead.org/git/?a=commitdiff_plain;h=78c412fcd53e1e5085e90cbd0ef43411e2eb6221;p=users%2Fsagi%2Fnvme-cli.git

Update documentation to use aliases

Firmware activate is now called 'fw-commit', so this patch updates the
documentation, documents the options, and renames the man page. The firmware
activate will alias to the new man page if requested.

Signed-off-by: Keith Busch <keith.busch@intel.com>
---

diff --git a/Documentation/nvme-fw-activate.1 b/Documentation/nvme-fw-commit.1
similarity index 52%
rename from Documentation/nvme-fw-activate.1
rename to Documentation/nvme-fw-commit.1
index 38ba512e..2a7f4961 100644
--- a/Documentation/nvme-fw-activate.1
+++ b/Documentation/nvme-fw-commit.1
@@ -1,13 +1,13 @@
 '\" t
-.\"     Title: nvme-fw-activate
-.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
-.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 12/10/2017
+.\"     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: 12/19/2017
 .\"    Manual: NVMe Manual
 .\"    Source: NVMe
 .\"  Language: English
 .\"
-.TH "NVME\-FW\-ACTIVATE" "1" "12/10/2017" "NVMe" "NVMe Manual"
+.TH "NVME\-FW\-COMMIT" "1" "12/19/2017" "NVMe" "NVMe Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -28,20 +28,21 @@
 .\" * MAIN CONTENT STARTS HERE *
 .\" -----------------------------------------------------------------
 .SH "NAME"
-nvme-fw-activate \- Used to verify and commit a firmware image\&.
+nvme-fw-commit \- Used to verify and commit a firmware image\&.
 .SH "SYNOPSIS"
 .sp
 .nf
-\fInvme fw\-activate\fR <device> [\-\-slot=<slot> | \-s <slot>]
+\fInvme fw\-commit\fR <device> [\-\-slot=<slot> | \-s <slot>]
                     [\-\-action=<action> | \-a <action>]
+                    [\-\-bpid=<boot\-partid> | \-b <boot\-partid> ]
 .fi
 .SH "DESCRIPTION"
 .sp
-For the NVMe device given, send an nvme Firmware Activate admin command and provides the results\&.
+For the NVMe device given, send an nvme Firmware Commit admin command and provides the results\&.
 .sp
-The Firmware Activate 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 activate 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\&.
+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 activate the firmware by issuing a reset through Linux sysfs, for example:
+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
@@ -58,13 +59,15 @@ If your kernel is not recent enough, you will need to remove and add the device
 .PP
 \-a <action>, \-\-action=<action>
 .RS 4
-Activate 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\&.
+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
@@ -91,13 +94,28 @@ T{
 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 Activate 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\&.
+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
+Specifiies the Boot partition that shall be used for the Commit Action, if applicable (default: 0)
 .RE
 .SH "EXAMPLES"
 .sp
@@ -109,18 +127,21 @@ Firmware Slot: Specifies the firmware slot that shall be used for the Activate A
 .sp -1
 .IP \(bu 2.3
 .\}
-Activate the last downloaded fw to slot 1\&.
+commit the last downloaded fw to slot 1\&.
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
-# nvme fw\-activate /dev/nvme0 \-\-slot=1 \-\-action=2
+# 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
diff --git a/Documentation/nvme-fw-activate.html b/Documentation/nvme-fw-commit.html
similarity index 88%
rename from Documentation/nvme-fw-activate.html
rename to Documentation/nvme-fw-commit.html
index 368f2bc1..4d790fb7 100644
--- a/Documentation/nvme-fw-activate.html
+++ b/Documentation/nvme-fw-commit.html
@@ -4,7 +4,7 @@
 <head>
 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
 <meta name="generator" content="AsciiDoc 8.6.8" />
-<title>nvme-fw-activate(1)</title>
+<title>nvme-fw-commit(1)</title>
 <style type="text/css">
 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
 
@@ -732,11 +732,11 @@ asciidoc.install();
 <body class="manpage">
 <div id="header">
 <h1>
-nvme-fw-activate(1) Manual Page
+nvme-fw-commit(1) Manual Page
 </h1>
 <h2>NAME</h2>
 <div class="sectionbody">
-<p>nvme-fw-activate -
+<p>nvme-fw-commit -
    Used to verify and commit a firmware image.
 </p>
 </div>
@@ -746,8 +746,9 @@ nvme-fw-activate(1) Manual Page
 <h2 id="_synopsis">SYNOPSIS</h2>
 <div class="sectionbody">
 <div class="verseblock">
-<pre class="content"><em>nvme fw-activate</em> &lt;device&gt; [--slot=&lt;slot&gt; | -s &lt;slot&gt;]
-                    [--action=&lt;action&gt; | -a &lt;action&gt;]</pre>
+<pre class="content"><em>nvme fw-commit</em> &lt;device&gt; [--slot=&lt;slot&gt; | -s &lt;slot&gt;]
+                    [--action=&lt;action&gt; | -a &lt;action&gt;]
+                    [--bpid=&lt;boot-partid&gt; | -b &lt;boot-partid&gt; ]</pre>
 <div class="attribution">
 </div></div>
 </div>
@@ -755,11 +756,11 @@ nvme-fw-activate(1) Manual Page
 <div class="sect1">
 <h2 id="_description">DESCRIPTION</h2>
 <div class="sectionbody">
-<div class="paragraph"><p>For the NVMe device given, send an nvme Firmware Activate admin command
+<div class="paragraph"><p>For the NVMe device given, send an nvme Firmware Commit admin command
 and provides the results.</p></div>
-<div class="paragraph"><p>The Firmware Activate command is used to verify that a valid firmware
+<div class="paragraph"><p>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 activate on the
+firmware slot. The host may select the firmware image to commit on the
 next controller reset (CC.EN transitions from ‘1’ to ‘0’, a PCI
 function level reset, and/or other Controller or NVM Subsystem Reset)
 as part of this command. The currently executing firmware revision may
@@ -767,7 +768,7 @@ be determined from the Firmware Revision field of the Identify Controller
 data structure as indicated in the Firmware Slot Information log page.</p></div>
 <div class="paragraph"><p>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 activate the firmware by issuing a
+driver are recent enough, you can commit the firmware by issuing a
 reset through Linux sysfs, for example:</p></div>
 <div class="listingblock">
 <div class="content">
@@ -789,7 +790,7 @@ the device some other way.</p></div>
 </dt>
 <dd>
 <p>
-        Activate Action: This field specifies the action that is taken
+        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.
 </p>
@@ -825,6 +826,16 @@ next reset.</p></td>
 <td align="left" valign="top"><p class="table">The image specified by the Firmware Slot field is requested to be
 activated immediately without reset.</p></td>
 </tr>
+<tr>
+<td align="left" valign="top"><p class="table">6</p></td>
+<td align="left" valign="top"><p class="table">Downloaded image replaces the Boot Partition specified by the Boot Partition
+ID field.</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">7</p></td>
+<td align="left" valign="top"><p class="table">Mark the Boot Partition specified in the BPID field as active and update
+BPINFO.ABPID.</p></td>
+</tr>
 </tbody>
 </table>
 </div>
@@ -838,11 +849,23 @@ activated immediately without reset.</p></td>
 <dd>
 <p>
         Firmware Slot: Specifies the firmware slot that shall be used for
-        the Activate Action, if applicable. If the value specified is 0h,
+        the Commit Action, if applicable. If the value specified is 0h,
         then the controller shall choose the firmware slot (slot 1 – 7)
         to use for the operation.
 </p>
 </dd>
+<dt class="hdlist1">
+--bpid=&lt;boot-partid&gt;
+</dt>
+<dt class="hdlist1">
+-b &lt;boot-partid&gt;
+</dt>
+<dd>
+<p>
+        Specifiies the Boot partition that shall be used for the Commit Action,
+        if applicable (default: 0)
+</p>
+</dd>
 </dl></div>
 </div>
 </div>
@@ -852,17 +875,23 @@ activated immediately without reset.</p></td>
 <div class="ulist"><ul>
 <li>
 <p>
-Activate the last downloaded fw to slot 1.
+commit the last downloaded fw to slot 1.
 </p>
 <div class="listingblock">
 <div class="content">
-<pre><code># nvme fw-activate /dev/nvme0 --slot=1 --action=2</code></pre>
+<pre><code># nvme fw-commit /dev/nvme0 --slot=1 --action=2</code></pre>
 </div></div>
 </li>
 </ul></div>
 </div>
 </div>
 <div class="sect1">
+<h2 id="_alias">ALIAS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>fw-activate</p></div>
+</div>
+</div>
+<div class="sect1">
 <h2 id="_nvme">NVME</h2>
 <div class="sectionbody">
 <div class="paragraph"><p>Part of the nvme-user suite</p></div>
@@ -872,7 +901,7 @@ Activate the last downloaded fw to slot 1.
 <div id="footnotes"><hr /></div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2017-08-28 10:19:30 EDT
+Last updated 2017-12-19 13:33:25 MST
 </div>
 </div>
 </body>
diff --git a/Documentation/nvme-fw-activate.txt b/Documentation/nvme-fw-commit.txt
similarity index 63%
rename from Documentation/nvme-fw-activate.txt
rename to Documentation/nvme-fw-commit.txt
index 55a23cdf..c164c5a2 100644
--- a/Documentation/nvme-fw-activate.txt
+++ b/Documentation/nvme-fw-commit.txt
@@ -1,24 +1,25 @@
-nvme-fw-activate(1)
-===================
+nvme-fw-commit(1)
+=================
 
 NAME
 ----
-nvme-fw-activate - Used to verify and commit a firmware image.
+nvme-fw-commit - Used to verify and commit a firmware image.
 
 SYNOPSIS
 --------
 [verse]
-'nvme fw-activate' <device> [--slot=<slot> | -s <slot>]
+'nvme fw-commit' <device> [--slot=<slot> | -s <slot>]
 		    [--action=<action> | -a <action>]
+		    [--bpid=<boot-partid> | -b <boot-partid> ]
 
 DESCRIPTION
 -----------
-For the NVMe device given, send an nvme Firmware Activate admin command
+For the NVMe device given, send an nvme Firmware Commit admin command
 and provides the results.
 
-The Firmware Activate command is used to verify that a valid firmware
+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 activate on the
+firmware slot. The host may select the firmware image to commit on the
 next controller reset (CC.EN transitions from ‘1’ to ‘0’, a PCI
 function level reset, and/or other Controller or NVM Subsystem Reset)
 as part of this command. The currently executing firmware revision may
@@ -27,7 +28,7 @@ data structure as indicated in the Firmware Slot Information log page.
 
 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 activate the firmware by issuing a
+driver are recent enough, you can commit the firmware by issuing a
 reset through Linux sysfs, for example:
 
 ------------
@@ -41,7 +42,7 @@ OPTIONS
 -------
 -a <action>::
 --action=<action>::
-	Activate Action: This field specifies the action that is taken
+	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.
 +
@@ -56,23 +57,36 @@ field. This image is activated at the next reset.
 next reset.
 |3|The image specified by the Firmware Slot field is requested to be
 activated immediately without reset.
+|6|Downloaded image replaces the Boot Partition specified by the Boot Partition
+ID field.
+|7|Mark the Boot Partition specified in the BPID field as active and update
+BPINFO.ABPID.
 |=================
 
 -s <slot>::
 --slot=<slot>::
 	Firmware Slot: Specifies the firmware slot that shall be used for
-	the Activate Action, if applicable. If the value specified is 0h,
+	the Commit Action, if applicable. If the value specified is 0h,
 	then the controller shall choose the firmware slot (slot 1 – 7)
 	to use for the operation.
 
+--bpid=<boot-partid>::
+-b <boot-partid>::
+	Specifiies the Boot partition that shall be used for the Commit Action,
+	if applicable (default: 0)
+
 EXAMPLES
 --------
-* Activate the last downloaded fw to slot 1.
+* commit the last downloaded fw to slot 1.
 +
 ------------
-# nvme fw-activate /dev/nvme0 --slot=1 --action=2
+# nvme fw-commit /dev/nvme0 --slot=1 --action=2
 ------------
 
+ALIAS
+-----
+
+fw-activate
 
 NVME
 ----
diff --git a/plugin.c b/plugin.c
index 5eb12bfc..ba0f55b5 100644
--- a/plugin.c
+++ b/plugin.c
@@ -21,18 +21,28 @@ static int help(int argc, char **argv, struct plugin *plugin)
 {
 	char man[0x100];
 	struct program *prog = plugin->parent;
+	char *str = argv[1];
+	int i;
 
 	if (argc == 1) {
 		general_help(plugin);
 		return 0;
 	}
 
-	if (plugin->name)
-		sprintf(man, "%s-%s-%s", prog->name, plugin->name, argv[1]);
-	else
-		sprintf(man, "%s-%s", prog->name, argv[1]);
-	if (execlp("man", "man", man, (char *)NULL))
-		perror(argv[1]);
+	for (i = 0; plugin->commands[i]; i++) {
+		struct command *cmd = plugin->commands[i];
+
+		if (strcmp(str, cmd->name))
+			if (!cmd->alias || (cmd->alias && strcmp(str, cmd->alias)))
+				continue;
+
+		if (plugin->name)
+			sprintf(man, "%s-%s-%s", prog->name, plugin->name, cmd->name);
+		else
+			sprintf(man, "%s-%s", prog->name, cmd->name);
+		if (execlp("man", "man", man, (char *)NULL))
+			perror(argv[1]);
+	}
 	return 0;
 }
 
@@ -125,13 +135,14 @@ int handle_plugin(int argc, char **argv, struct plugin *plugin)
 	while (*str == '-')
 		str++;
 
+	if (!strcmp(str, "help"))
+		return help(argc, argv, plugin);
+	if (!strcmp(str, "version"))
+		return version(plugin);
+
 	for (; plugin->commands[i]; i++) {
 		struct command *cmd = plugin->commands[i];
 
-		if (!strcmp(str, "help"))
-			return help(argc, argv, plugin);
-		if (!strcmp(str, "version"))
-			return version(plugin);
 		if (strcmp(str, cmd->name))
 			if (!cmd->alias || (cmd->alias && strcmp(str, cmd->alias)))
 				continue;