From e2d6a6e9388439f5c5df8df5c68d620b31d06659 Mon Sep 17 00:00:00 2001
From: Warner Losh <imp@FreeBSD.org>
Date: Fri, 1 May 2020 20:29:51 +0000
Subject: [PATCH] Document the passthru commands.

Reviewed by: bcr@ (earlier version)
Differential Revision: https://reviews.freebsd.org/D24639
---
 sbin/nvmecontrol/nvmecontrol.8 | 70 ++++++++++++++++++++++++++++++++++
 sbin/nvmecontrol/passthru.c    |  2 +-
 2 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/sbin/nvmecontrol/nvmecontrol.8 b/sbin/nvmecontrol/nvmecontrol.8
index 2c16de4b0092..a9796cf735da 100644
--- a/sbin/nvmecontrol/nvmecontrol.8
+++ b/sbin/nvmecontrol/nvmecontrol.8
@@ -194,6 +194,14 @@
 .\" .Nm
 .\" .Ic wdc purge-monitor
 .\" .Aq device-id
+.Nm
+.Ic admin-passthru
+.Op args
+.Aq Ar device-id
+.Nm
+.Ic io-passthru
+.Op args
+.Aq Ar namespace-id
 .Sh DESCRIPTION
 NVM Express (NVMe) is a storage protocol standard, for SSDs and other
 high-speed storage devices over PCI Express.
@@ -466,6 +474,68 @@ the drive's serial number and the type of dump it is followed
 by .bin.
 These logs must be sent to the vendor for analysis.
 This tool only provides a way to extract them.
+.Ss passthru
+The
+.Dq admin-passthru
+and
+.Dq io-passthru
+commands send NVMe commands to
+either the administrative or the data part of the device.
+These commands are expected to be compatible with nvme-cli.
+Please see
+.St The NVMe Standard
+for details.
+.Bl -tag -width 16n
+.It Fl o -opcode Ar opcode
+Opcode to send.
+.It Fl 2 -cdw2 Ar value
+32-bit value for CDW2.
+.It Fl 3 -cdw3 Ar value
+32-bit value for CDW3.
+.It Fl 4 -cdw10 Ar value
+32-bit value for CDW10.
+.It Fl 5 -cdw11 Ar value
+32-bit value for CDW11.
+.It Fl 6 -cdw12 Ar value
+32-bit value for CDW12.
+.It Fl 7 -cdw13 Ar value
+32-bit value for CDW13.
+.It Fl 8 -cdw14 Ar value
+32-bit value for CDW14.
+.It Fl 9 -cdw15 Ar value
+32-bit value for CDW15.
+.It Fl l -data-len
+Length of the data for I/O (bytes).
+.It Fl m -metadata-len
+Length of the metadata segment for command (bytes).
+This is ignored and not implemented in
+.Xr nvme 4 .
+.It Fl f -flags
+Nvme command flags.
+.It Fl n -namespace-id
+Namespace ID for command (Ignored).
+.It Fl p -prefill
+Value to prefill payload with.
+.It Fl b -raw-binary
+Output in binary format (otherwise a hex dump is produced).
+.It Fl d -dry-run
+Do not actually execute the command, but perform sanity checks on it.
+.It Fl r -read
+Command reads data from the device.
+.It Fl s -show-command
+Show all the command values on stdout.
+.It Fl w -write
+Command writes data to the device.
+.El
+Send arbitrary commands to the device.
+Can be used to extract vendor specific logs.
+Transfers to/from the device possible, but limited to
+.Dv MAXPHYS
+bytes.
+Commands either read data or write it, but not both.
+Commands needing metadata are not supported by the
+.Xr nvme 4
+drive.
 .Sh DEVICE NAMES
 Where
 .Aq Ar namespace-id
diff --git a/sbin/nvmecontrol/passthru.c b/sbin/nvmecontrol/passthru.c
index ec7bd0517edc..87ba322ca3c3 100644
--- a/sbin/nvmecontrol/passthru.c
+++ b/sbin/nvmecontrol/passthru.c
@@ -292,7 +292,7 @@ static struct cmd io_pass_cmd = {
 	.ctx_size = sizeof(struct options),
 	.opts = opts,
 	.args = args,
-	.descr = "Send a pass through Admin command to the specified device",
+	.descr = "Send a pass through I/O command to the specified device",
 };
 
 CMD_COMMAND(admin_pass_cmd);