Date: Mon, 19 Oct 2020 20:42:01 +0000 (UTC) From: Alexander Motin <mav@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-12@freebsd.org Subject: svn commit: r366860 - stable/12/sbin/nvmecontrol Message-ID: <202010192042.09JKg12N079791@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mav Date: Mon Oct 19 20:42:01 2020 New Revision: 366860 URL: https://svnweb.freebsd.org/changeset/base/366860 Log: MFC r360546, r360547 (by imp): Various improvements to this man page: o Be consistent about device-id and namespace-id o Use consistent arg markup for these o document you can use disk names too o document nsid command better o document the idenntify command o add a couple of examples. Modified: stable/12/sbin/nvmecontrol/nvmecontrol.8 stable/12/sbin/nvmecontrol/passthru.c Directory Properties: stable/12/ (props changed) Modified: stable/12/sbin/nvmecontrol/nvmecontrol.8 ============================================================================== --- stable/12/sbin/nvmecontrol/nvmecontrol.8 Mon Oct 19 20:40:03 2020 (r366859) +++ stable/12/sbin/nvmecontrol/nvmecontrol.8 Mon Oct 19 20:42:01 2020 (r366860) @@ -1,4 +1,5 @@ .\" +.\" Copyright (c) 2020 Warner Losh <imp@FreeBSD.org> .\" Copyright (c) 2018-2019 Alexander Motin <mav@FreeBSD.org> .\" Copyright (c) 2012 Intel Corporation .\" All rights reserved. @@ -34,7 +35,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 5, 2019 +.Dd April 30, 2020 .Dt NVMECONTROL 8 .Os .Sh NAME @@ -47,8 +48,8 @@ .Ic identify .Op Fl v .Op Fl x -.Aq device id -.Aq namespace id +.Op Fl n Ar nsid +.Aq Ar device-id | Ar namespace-id .Nm .Ic perftest .Aq Fl n Ar num_threads @@ -56,10 +57,10 @@ .Op Fl p .Aq Fl s Ar size_in_bytes .Aq Fl t Ar time_in_sec -.Aq namespace id +.Aq Ar namespace-id .Nm .Ic reset -.Aq controller id +.Aq Ar device-id .Nm .Ic logpage .Aq Fl p Ar page_id @@ -69,26 +70,25 @@ .Op Fl f Ar LSP .Op Fl i Ar LSI .Op Fl r -.Aq device id -.Aq namespace id +.Aq Ar device-id | Ar namespace-id .Nm .Ic ns active -.Aq device id +.Aq Ar device-id .Nm .Ic ns allocated -.Aq device id +.Aq Ar device-id .Nm .Ic ns attach .Aq Fl n Ar nsid .Aq Fl c Ar cntid -.Aq device id +.Aq Ar device-id .Nm .Ic ns attached .Aq Fl n Ar nsid -.Aq device id +.Aq Ar device-id .Nm .Ic ns controllers -.Aq device id +.Aq Ar device-id .Nm .Ic ns create .Aq Fl s Ar nsze @@ -100,33 +100,32 @@ .Op Fl l Ar pil .Op Fl L Ar flbas .Op Fl d Ar dps -.Aq device id +.Aq Ar device-id .Nm .Ic ns delete .Aq Fl n Ar nsid -.Aq device id +.Aq Ar device-id .Nm .Ic ns detach .Aq Fl n Ar nsid .Aq Fl c Ar cntid -.Aq device id +.Aq Ar device-id .Nm .Ic ns identify .Op Fl v .Op Fl x .Aq Fl n Ar nsid -.Aq device id +.Aq Ar device-id .Nm .Ic nsid -.Aq device id -.Aq namespace id +.Aq Ar device-id | Ar namespace-id .Nm .Ic resv acquire .Aq Fl c Ar crkey .Op Fl p Ar prkey .Aq Fl t Ar rtype .Aq Fl a Ar racqa -.Aq namespace id +.Aq Ar namespace-id .Nm .Ic resv register .Op Fl c Ar crkey @@ -134,25 +133,25 @@ .Aq Fl r Ar rrega .Op Fl i Ar iekey .Op Fl p Ar cptpl -.Aq namespace id +.Aq Ar namespace-id .Nm .Ic resv release .Aq Fl c Ar crkey .Aq Fl t Ar rtype .Aq Fl a Ar rrela -.Aq namespace id +.Aq Ar namespace-id .Nm .Ic resv report .Op Fl e .Op Fl v .Op Fl x -.Aq namespace id +.Aq Ar namespace-id .Nm .Ic firmware .Op Fl s Ar slot .Op Fl f Ar path_to_firmware .Op Fl a -.Aq device id +.Aq Ar device-id .Nm .Ic format .Op Fl f Ar fmt @@ -161,8 +160,7 @@ .Op Fl l Ar pil .Op Fl E .Op Fl C -.Aq device id -.Aq namespace id +.Aq Ar device-id | Ar namespace-id .Nm .Ic sanitize .Aq Fl a Ar sanact @@ -172,7 +170,7 @@ .Op Fl r .Op Fl I .Op Fl U -.Aq device id +.Aq Ar device-id .Nm .Ic power .Op Fl l @@ -181,25 +179,65 @@ .Nm .Ic wdc cap-diag .Op Fl o path_template -.Aq device id +.Aq Ar device-id .Nm .Ic wdc drive-log .Op Fl o path_template -.Aq device id +.Aq Ar device-id .Nm .Ic wdc get-crash-dump .Op Fl o path_template -.Aq device id +.Aq Ar device-id .\" .Nm .\" .Ic wdc purge -.\" .Aq device id +.\" .Aq device-id .\" .Nm .\" .Ic wdc purge-monitor -.\" .Aq device id +.\" .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. .Pp +.Ss identify +The identify commands reports information from the drive's +.Dv IDENTIFY_CONTROLLER +if a +.Ar device-id +is specified. +It reports +.Dv IDENTIFY_NAMESPACE +data if a +.Ar namespace-id +is specified. +When used with disk names, the +.Dv IDENTIFY_NAMESPACE +data is reported, unless the namespace +.Ar nsid +is overridden with the +.Fl n +flag. +Then that namespace's data is reported, if it exists. +The command accepts the following parameters: +.Bl -tag -width 6n +.It Fl n +The namespace +.Aq nsid +to use instead of the namespace associated with the device. +A +.Ar nsid +of +.Dq 0 +is used to retrieve the +.Dv IDENTIFY_CONTROLLER +data associated with that drive. .Ss logpage The logpage command knows how to print log pages of various types. It also knows about vendor specific log pages from hgst/wdc and intel. @@ -250,6 +288,12 @@ will set Retain Asynchronous Event. Various namespace management commands. If namespace management is supported by device, allow list, create and delete namespaces, list, attach and detach controllers to namespaces. +.Ss nsid +Reports the namespace id and controller device associated with the +.Aq Ar namespace-id +or +.Aq Ar device-id +argument. .Ss resv acquire Acquire or preempt namespace reservation, using specified parameters: .Bl -tag -width 6n @@ -430,19 +474,116 @@ the drive's serial number and the type of dump it is f 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 +is required, you can use either the +.Pa nvmeXnsY +device, or the disk device such as +.Pa ndaZ +or +.Pa nvdZ . +The leading +.Pa /dev/ +is omitted. +Where +.Aq Ar device-id +is required, you can use either the +.Pa nvmeX +device, or the disk device such as +.Pa nda Z +or +.Pa nvdZ . +For commands that take an optional +.Aq nsid +you can use it to get information on other namespaces, or to query the +drive itself. +A +.Aq nsid +of +.Dq 0 +means query the drive itself. .Sh EXAMPLES .Dl nvmecontrol devlist .Pp Display a list of NVMe controllers and namespaces along with their device nodes. .Pp .Dl nvmecontrol identify nvme0 +.Dl nvmecontrol identify -n 0 nvd0 .Pp -Display a human-readable summary of the nvme0 IDENTIFY_CONTROLLER data. +Display a human-readable summary of the nvme0 +.Dv IDENTIFY_CONTROLLER +data. +In this example, nvd0 is connected to nvme0. .Pp .Dl nvmecontrol identify -x -v nvme0ns1 +.Dl nvmecontrol identify -x -v -n 1 nvme0 .Pp -Display an hexadecimal dump of the nvme0 IDENTIFY_NAMESPACE data for namespace -1. +Display an hexadecimal dump of the nvme0 +.Dv IDENTIFY_NAMESPACE +data for namespace 1. .Pp .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1 .Pp @@ -451,8 +592,10 @@ Each thread will issue a single 512 byte read command. Results are printed to stdout when 30 seconds expires. .Pp .Dl nvmecontrol reset nvme0 +.Dl nvmecontrol reset nda4 .Pp Perform a controller-level reset of the nvme0 controller. +In this example, nda4 is wired to nvme0. .Pp .Dl nvmecontrol logpage -p 1 nvme0 .Pp @@ -500,6 +643,24 @@ Set the current power mode. .Dl nvmecontrol power nvme0 .Pp Get the current power mode. +.Pp +.Dl nvmecontrol identify -n 0 nda0 +.Pp +Identify the drive data associated with the +.Pa nda0 +device. +The corresponding +.Pa nvmeX +devices is used automatically. +.Pp +.Dl nvmecontrol identify nda0 +.Pp +Get the namespace parameters associated with the +.Pa nda0 +device. +The corresponding +.Pa nvmeXnsY +device is used automatically. .Sh DYNAMIC LOADING The directories .Pa /lib/nvmecontrol Modified: stable/12/sbin/nvmecontrol/passthru.c ============================================================================== --- stable/12/sbin/nvmecontrol/passthru.c Mon Oct 19 20:40:03 2020 (r366859) +++ stable/12/sbin/nvmecontrol/passthru.c Mon Oct 19 20:42:01 2020 (r366860) @@ -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);
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202010192042.09JKg12N079791>