From: Minwoo Im Date: Tue, 30 Jan 2018 10:36:49 +0000 (+0900) Subject: nvme-cli: update documentations to sync up with subcommands X-Git-Tag: v1.6~91^2 X-Git-Url: https://www.infradead.org/git/?a=commitdiff_plain;h=1394a3f7aff8fda830a09a49911b7bb8ba8cf6b6;p=users%2Fhch%2Fnvme-cli.git nvme-cli: update documentations to sync up with subcommands Update all documentations to sync up with built-in plugin subcommands. Not only options supported by subcommands, But few descriptions have not been updated with implementations. Sync-up documentation with subcommands implementations. Signed-off-by: Minwoo Im --- diff --git a/Documentation/cmds-main.txt b/Documentation/cmds-main.txt index 5d5b8f6..3b40fa1 100644 --- a/Documentation/cmds-main.txt +++ b/Documentation/cmds-main.txt @@ -31,6 +31,9 @@ linknvme:nvme-get-feature[1]:: linknvme:nvme-get-log[1]:: Generic Get Log +linknvme:nvme-telemetry-log[1]:: + Telemetry Host-Initiated Log + linknvme:nvme-smart-log[1]:: Retrieve Smart Log @@ -64,6 +67,9 @@ linknvme:nvme-io-passthru[1]:: linknvme:nvme-list-ns[1]:: List all nvme namespaces +linknvme:nvme-ns-descs[1]:: + Identify Namespace Identification Descriptor + linknvme:nvme-list[1]:: List all nvme controllers diff --git a/Documentation/nvme-admin-passthru.1 b/Documentation/nvme-admin-passthru.1 index 4bddd8a..0662764 100644 --- a/Documentation/nvme-admin-passthru.1 +++ b/Documentation/nvme-admin-passthru.1 @@ -2,12 +2,12 @@ .\" Title: nvme-admin-passthru .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" Date: 12/10/2017 +.\" Date: 01/30/2018 .\" Manual: NVMe Manual .\" Source: NVMe .\" Language: English .\" -.TH "NVME\-ADMIN\-PASSTHR" "1" "12/10/2017" "NVMe" "NVMe Manual" +.TH "NVME\-ADMIN\-PASSTHR" "1" "01/30/2018" "NVMe" "NVMe Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -42,7 +42,8 @@ nvme-admin-passthru \- Submit an arbitrary admin command, return results [\-\-input\-file= | \-f ] [\-\-read | \-r ] [\-\-write | \-w] [\-\-timeout= | \-t ] - [\-\-show\-command | \-\-dry\-run | \-s] + [\-\-show\-command | \-s] + [\-\-dry\-run | \-d] [\-\-raw\-binary | \-b] [\-\-prefill= | \-p ] .fi @@ -100,9 +101,17 @@ The data length for the buffer used for this command\&. The metadata length for the buffer used for this command\&. .RE .PP -\-s, \-\-show\-cmd, \-\-dry\-run +\-s, \-\-show\-cmd .RS 4 -Do not actually send the command; print out the command that would be sent\&. +Print out the command to be sent\&. +.RE +.PP +\-d, \-\-dry\-run +.RS 4 +Do not actually send the command\&. If want to use \-\-dry\-run option, \-\-show\-cmd option +\fImust\fR +be set\&. Otherwise \-\-dry\-run optionn will be +\fIignored\fR\&. .RE .PP \-b, \-\-raw\-binary diff --git a/Documentation/nvme-admin-passthru.html b/Documentation/nvme-admin-passthru.html index e74aee0..d191809 100644 --- a/Documentation/nvme-admin-passthru.html +++ b/Documentation/nvme-admin-passthru.html @@ -3,7 +3,7 @@ - + nvme-admin-passthru(1) + + + + +
+
+

SYNOPSIS

+
+
+
nvme ns-descs <device> [--namespace-id=<nsid> | -n <nsid>]
+                        [--raw-binary | -b]
+                        [--output-format=<fmt> | -o <fmt>]
+
+
+
+
+
+

DESCRIPTION

+
+

For the NVMe device given, sends an identify for a list of namespace +identification descriptor structures command and provides the result and +returned structure.

+

The <device> parameter is mandatory and may be either the NVMe character +device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1). +If the character device is given, the '--namespace-id' option is +mandatory, otherwise it will use the ns-id of the namespace for the block +device you opened. For block devices, the ns-id used can be overridden +with the same option.

+

On success, the structure may be returned in one of several ways depending +on the option flags; the structure may be parsed by the program or the +raw buffer may be printed to stdout.

+
+
+
+

OPTIONS

+
+
+
+-n <nsid> +
+
+--namespace-id=<nsid> +
+
+

+ Retrieve the identify namespace identification descriptor structure + for the given nsid. This is required for the character devices, or + overrides the block nsid if given. +

+
+
+-b +
+
+--raw-binary +
+
+

+ Print the raw buffer to stdout. Structure is not parsed by + program. +

+
+
+-o <format> +
+
+--output-format=<format> +
+
+

+ Set the reporting format to normal, json, or binary. + Only one output format can be used at a time. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +If using the character device or overriding namespace #2: +

    +
    +
    +
    # nvme ns-descs /dev/nvme0 -n 1
+# nvme ns-descs /dev/nvme0n1 -n 2
+# nvme ns-descs /dev/nvme0 --namespace-id=1
    +
    +
    • +
  • +

    +Have the program return the raw structure in binary: +

    +
    +
    +
    # nvme ns-descs /dev/nvme0n1 --raw-binary > ns_descs.raw
+# nvme ns-descs /dev/nvme0n1 -b > ns_descs.raw
    +
    +

    It is probably a bad idea to not redirect stdout when using this mode.

    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-ns-descs.txt b/Documentation/nvme-ns-descs.txt new file mode 100644 index 0000000..8afeba5 --- /dev/null +++ b/Documentation/nvme-ns-descs.txt @@ -0,0 +1,74 @@ +nvme-ns-descs(1) +================ + +NAME +---- +nvme-ns-descs - Send NVMe Identify for a list of Namespace Identification + Descriptor structure, return result and structure + +SYNOPSIS +-------- +[verse] +'nvme ns-descs' [--namespace-id= | -n ] + [--raw-binary | -b] + [--output-format= | -o ] + +DESCRIPTION +----------- +For the NVMe device given, sends an identify for a list of namespace +identification descriptor structures command and provides the result and +returned structure. + +The parameter is mandatory and may be either the NVMe character +device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1). +If the character device is given, the `'--namespace-id'` option is +mandatory, otherwise it will use the ns-id of the namespace for the block +device you opened. For block devices, the ns-id used can be overridden +with the same option. + +On success, the structure may be returned in one of several ways depending +on the option flags; the structure may be parsed by the program or the +raw buffer may be printed to stdout. + +OPTIONS +------- +-n :: +--namespace-id=:: + Retrieve the identify namespace identification descriptor structure + for the given nsid. This is required for the character devices, or + overrides the block nsid if given. + +-b:: +--raw-binary:: + Print the raw buffer to stdout. Structure is not parsed by + program. + +-o :: +--output-format=:: + Set the reporting format to 'normal', 'json', or 'binary'. + Only one output format can be used at a time. + + +EXAMPLES +-------- +* If using the character device or overriding namespace #2: ++ +------------ +# nvme ns-descs /dev/nvme0 -n 1 +# nvme ns-descs /dev/nvme0n1 -n 2 +# nvme ns-descs /dev/nvme0 --namespace-id=1 +------------ ++ + +* Have the program return the raw structure in binary: ++ +------------ +# nvme ns-descs /dev/nvme0n1 --raw-binary > ns_descs.raw +# nvme ns-descs /dev/nvme0n1 -b > ns_descs.raw +------------ ++ +It is probably a bad idea to not redirect stdout when using this mode. + +NVME +---- +Part of the nvme-user suite diff --git a/Documentation/nvme-read.1 b/Documentation/nvme-read.1 index c53f1a5..b64c0eb 100644 --- a/Documentation/nvme-read.1 +++ b/Documentation/nvme-read.1 @@ -2,12 +2,12 @@ .\" Title: nvme-read .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" Date: 12/10/2017 +.\" Date: 01/30/2018 .\" Manual: NVMe Manual .\" Source: NVMe .\" Language: English .\" -.TH "NVME\-READ" "1" "12/10/2017" "NVMe" "NVMe Manual" +.TH "NVME\-READ" "1" "01/30/2018" "NVMe" "NVMe Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -43,8 +43,13 @@ nvme-read \- Send an NVMe Read command, provide results [\-\-app\-tag\-mask= | \-m ] [\-\-app\-tag= | \-a ] [\-\-limited\-retry | \-l] - [\-\-latency | \-t] [\-\-force\-unit\-access | \-f] + [\-\-dir\-type= | \-T ] + [\-\-dir\-spec= | \-S ] + [\-\-dsm= | \-D ] + [\-\-show\-command | \-v] + [\-\-dry\-run | \-w] + [\-\-latency | \-t] .fi .SH "DESCRIPTION" .sp @@ -141,7 +146,35 @@ Optional application tag mask when used with protection information\&. Set the force\-unit access flag\&. .RE .PP -\-\-latency, \-t +\-T , \-\-dir\-type= +.RS 4 +Optional directive type\&. The nvme\-cli only enforces the value be in the defined range for the directive type, though the NVMe specifcation (1\&.3a) defines only one directive, 01h, for write stream idenfiers\&. +.RE +.PP +\-S , \-\-dir\-spec= +.RS 4 +Optional field for directive specifics\&. When used with write streams, this value is defined to be the write stream identifier\&. The nvme\-cli will not validate the stream requested is within the controller\(cqs capabilities\&. +.RE +.PP +\-D , \-\-dsm= +.RS 4 +The optional data set management attributes for this command\&. The argument for this is the lower 16 bits of the DSM field in a write command; the upper 16 bits of the field come from the directive specific field, if used\&. This may be used to set attributes for the LBAs being written, like access frequency, type, latency, among other things, as well as yet to be defined types\&. Please consult the NVMe specification for detailed breakdown of how to use this field\&. +.RE +.PP +\-v, \-\-show\-cmd +.RS 4 +Print out the command to be sent\&. +.RE +.PP +\-w, \-\-dry\-run +.RS 4 +Do not actually send the command\&. If want to use \-\-dry\-run option, \-\-show\-cmd option +\fImust\fR +be set\&. Otherwise \-\-dry\-run optionn will be +\fIignored\fR\&. +.RE +.PP +\-t, \-\-latency .RS 4 Print out the latency the IOCTL took (in us)\&. .RE diff --git a/Documentation/nvme-read.html b/Documentation/nvme-read.html index c9d0c1b..8b9a7f5 100644 --- a/Documentation/nvme-read.html +++ b/Documentation/nvme-read.html @@ -3,7 +3,7 @@ - + nvme-read(1) - - - - -
-
-

SYNOPSIS

-
-
-
nvme sanitize-log <device>
-
-
-
-
-
-

DESCRIPTION

-
-

Retrieves the NVMe Sanitize log page from an NVMe device and provides the -status of sanitize command.

-

The <device> parameter is mandatory NVMe character device (ex: /dev/nvme0).

-

Expected status and description :-

-
- --- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Status Code Description

0x0000

NVM subsystem has never been sanitized.

0x0001

The most recent sanitize operation completed successfully.

0x0002

A sanitize operation is currently in progress.

0x0003

The most recent sanitize operation failed.

0x0100

Global Data Erased bit -If set to 1 then non-volatile storage in the NVM subsystem has -not been written to: - a) since being manufactured and the NVM subsystem has never been sanitized; or - b) since the most recent successful sanitize operation. -If cleared to 0, then non-volatile storage in the NVM subsystem has been written to: - a) since being manufactured and the NVM subsystem has never been sanitized; or - b) since the most recent successful sanitize operation of the NVM subsystem.

-
-

Sanitize Progress - percentage complete

-

On success it returns 0, error code otherwise.

-
-
-
-

OPTIONS

-
-

No options yet.

-
-
-
-

EXAMPLES

-
-
    -
  • -

    -Has the program issue Sanitize-log Command : -

    -
    -
    -
    # nvme sanitize-log /dev/nvme0
    -
    -
    • -
-
-
-
-

NVME

-
-

Part of the nvme-user suite.

-
-
-
-
- - - + + + + + +nvme-sanitize-log(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme sanitize-log <device> [--output-format=<fmt> | -o <fmt>]
+                             [--human-readable | -H]
+                             [--raw-binary | -b]
+
+
+
+
+
+

DESCRIPTION

+
+

Retrieves the NVMe Sanitize log page from an NVMe device and provides the +status of sanitize command.

+

The <device> parameter is mandatory NVMe character device (ex: /dev/nvme0).

+

Expected status and description :-

+
+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status Code Description

0x0000

NVM subsystem has never been sanitized.

0x0001

The most recent sanitize operation completed successfully.

0x0002

A sanitize operation is currently in progress.

0x0003

The most recent sanitize operation failed.

0x0100

Global Data Erased bit +If set to 1 then non-volatile storage in the NVM subsystem has +not been written to: + a) since being manufactured and the NVM subsystem has never been sanitized; or + b) since the most recent successful sanitize operation. +If cleared to 0, then non-volatile storage in the NVM subsystem has been written to: + a) since being manufactured and the NVM subsystem has never been sanitized; or + b) since the most recent successful sanitize operation of the NVM subsystem.

+
+

Sanitize Progress - percentage complete

+

On success it returns 0, error code otherwise.

+
+
+
+

OPTIONS

+
+
+
+-o <format> +
+
+--output-format=<format> +
+
+

+ Set the reporting format to normal, json, or + binary. Only one output format can be used at a time. +

+
+
+-H +
+
+--human-readable +
+
+

+ This option will parse and format many of the bit fields + into human-readable formats. +

+
+
+-b +
+
+--raw-binary +
+
+

+ Print the raw buffer to stdout. Structure is not parsed by + program. This overrides the vendor specific and human readable options. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Has the program issue Sanitize-log Command : +

    +
    +
    +
    # nvme sanitize-log /dev/nvme0
    +
    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite.

+
+
+
+
+ + + diff --git a/Documentation/nvme-sanitize-log.txt b/Documentation/nvme-sanitize-log.txt index a4ff729..3c3b73e 100644 --- a/Documentation/nvme-sanitize-log.txt +++ b/Documentation/nvme-sanitize-log.txt @@ -8,7 +8,9 @@ nvme-sanitize-log - Send NVMe sanitize-log Command, return result SYNOPSIS -------- [verse] -'nvme sanitize-log' +'nvme sanitize-log' [--output-format= | -o ] + [--human-readable | -H] + [--raw-binary | -b] DESCRIPTION ----------- @@ -52,7 +54,20 @@ On success it returns 0, error code otherwise. OPTIONS ------- -No options yet. +-o :: +--output-format=:: + Set the reporting format to 'normal', 'json', or + 'binary'. Only one output format can be used at a time. + +-H:: +--human-readable:: + This option will parse and format many of the bit fields + into human-readable formats. + +-b:: +--raw-binary:: + Print the raw buffer to stdout. Structure is not parsed by + program. This overrides the vendor specific and human readable options. EXAMPLES -------- diff --git a/Documentation/nvme-security-recv.1 b/Documentation/nvme-security-recv.1 index f866bba..20eb3ac 100644 --- a/Documentation/nvme-security-recv.1 +++ b/Documentation/nvme-security-recv.1 @@ -2,12 +2,12 @@ .\" Title: nvme-security-recv .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" Date: 12/10/2017 +.\" Date: 01/30/2018 .\" Manual: NVMe Manual .\" Source: NVMe .\" Language: English .\" -.TH "NVME\-SECURITY\-RECV" "1" "12/10/2017" "NVMe" "NVMe Manual" +.TH "NVME\-SECURITY\-RECV" "1" "01/30/2018" "NVMe" "NVMe Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -32,13 +32,13 @@ nvme-security-recv \- Security Recv command .SH "SYNOPSIS" .sp .nf -\fInvme security\-recv\fR [] [\-\-size= | \-x ] +\fInvme security\-recv\fR [\-\-size= | \-x ] [\-\-secp= | \-p ] [\-\-spsp= | \-s ] [\-\-nssf= | \-N ] - [\-\-tl= | \-t ] + [\-\-al= | \-t ] [\-\-namespace\-id= | \-n ] - [\-b | \-\-raw\-binary] + [\-\-raw\-binary | \-b] .fi .SH "DESCRIPTION" .sp @@ -74,7 +74,7 @@ Security Protocol: This field specifies the security protocol as defined in SPC\ SP Specific: The value of this field is specific to the Security Protocol as defined in SPC\-4\&. .RE .PP -\-a , \-\-al= +\-t , \-\-al= .RS 4 Allocation Length: The value of this field is specific to the Security Protocol as defined in SPC\-4\&. .RE diff --git a/Documentation/nvme-security-recv.html b/Documentation/nvme-security-recv.html index 7c668bc..c6f1611 100644 --- a/Documentation/nvme-security-recv.html +++ b/Documentation/nvme-security-recv.html @@ -3,7 +3,7 @@ - + nvme-security-recv(1) + + + + +
+
+

SYNOPSIS

+
+
+
nvme telemetry-log <device> [--output-file=<file> | -o <file>]
+                      [--host-generate=<gen> | -h <gen>]
+
+
+
+
+
+

DESCRIPTION

+
+

Retrieves an Telemetry Host-Initiated log page from an NVMe device and provides +the retuned structure.

+

The <device> parameter is mandatory and may be either the NVMe character +device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1).

+

On success, the returned log structure will be in raw binary format only with +--output-file option which is mandatory.

+
+
+
+

OPTIONS

+
+
+
+-o <file> +
+
+--output-file=<file> +
+
+

+ File name to which raw binary data will be saved to. +

+
+
+-h <gen> +
+
+--host-generate=<gen> +
+
+

+ If set to 1, controller shall capture the Telemetry Host-Initiated data + representing the internal state of the controller at the time the + associated Get Log Page command is processed. + If cleated to 0, controller shall not update this data. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Retrieve Telemetry Host-Initiated data to telemetry_log.bin +

    +
    +
    +
    # nvme telemetry-log /dev/nvme0 --output-file=telemetry_log.bin
    +
    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-telemetry-log.txt b/Documentation/nvme-telemetry-log.txt new file mode 100644 index 0000000..804c241 --- /dev/null +++ b/Documentation/nvme-telemetry-log.txt @@ -0,0 +1,48 @@ +nvme-telemetry-log(1) +===================== + +NAME +---- +nvme-telemetry-log - Retrieves a Telemetry Host-Initiated log page from an NVMe device + +SYNOPSIS +-------- +[verse] +'nvme telemetry-log' [--output-file= | -o ] + [--host-generate= | -h ] + +DESCRIPTION +----------- +Retrieves an Telemetry Host-Initiated log page from an NVMe device and provides +the retuned structure. + +The parameter is mandatory and may be either the NVMe character +device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1). + +On success, the returned log structure will be in raw binary format _only_ with +--output-file option which is mandatory. + +OPTIONS +------- +-o :: +--output-file=:: + File name to which raw binary data will be saved to. + +-h :: +--host-generate=:: + If set to 1, controller shall capture the Telemetry Host-Initiated data + representing the internal state of the controller at the time the + associated Get Log Page command is processed. + If cleated to 0, controller shall _not_ update this data. + +EXAMPLES +-------- +* Retrieve Telemetry Host-Initiated data to telemetry_log.bin ++ +------------ +# nvme telemetry-log /dev/nvme0 --output-file=telemetry_log.bin +------------ + +NVME +---- +Part of the nvme-user suite diff --git a/Documentation/nvme-wdc-id-ctrl.1 b/Documentation/nvme-wdc-id-ctrl.1 index 6be1f74..fa7bfea 100644 --- a/Documentation/nvme-wdc-id-ctrl.1 +++ b/Documentation/nvme-wdc-id-ctrl.1 @@ -2,12 +2,12 @@ .\" Title: nvme-wdc-id-ctrl .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" Date: 12/10/2017 +.\" Date: 01/30/2018 .\" Manual: NVMe Manual .\" Source: NVMe .\" Language: English .\" -.TH "NVME\-WDC\-ID\-CTRL" "1" "12/10/2017" "NVMe" "NVMe Manual" +.TH "NVME\-WDC\-ID\-CTRL" "1" "01/30/2018" "NVMe" "NVMe Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -33,6 +33,7 @@ nvme-wdc-id-ctrl \- Send NVMe Identify Controller, return result and structure .sp .nf \fInvme wdc id\-ctrl\fR [\-v | \-\-vendor\-specific] [\-b | \-\-raw\-binary] + [\-H | \-\-human\-readable] [\-o | \-\-output\-format=] .fi .SH "DESCRIPTION" diff --git a/Documentation/nvme-wdc-id-ctrl.html b/Documentation/nvme-wdc-id-ctrl.html index dbbe29e..76a4703 100644 --- a/Documentation/nvme-wdc-id-ctrl.html +++ b/Documentation/nvme-wdc-id-ctrl.html @@ -3,7 +3,7 @@ - + nvme-wdc-id-ctrl(1)