From 9e9f341e878a44f8db131d52e854fcfd35e534e4 Mon Sep 17 00:00:00 2001 From: Keith Busch Date: Fri, 29 May 2015 09:31:48 -0600 Subject: [PATCH] Add html documentation Signed-off-by: Keith Busch --- Documentation/Makefile | 31 +- Documentation/asciidoc.conf | 97 +++ Documentation/cmds-main.txt | 84 ++ Documentation/install-webdoc.sh | 39 + Documentation/nvme-admin-passthru.1 | 50 +- Documentation/nvme-admin-passthru.html | 969 ++++++++++++++++++++++ Documentation/nvme-admin-passthru.txt | 19 +- Documentation/nvme-compare.html | 819 ++++++++++++++++++ Documentation/nvme-error-log.html | 861 +++++++++++++++++++ Documentation/nvme-flush.html | 809 ++++++++++++++++++ Documentation/nvme-format.html | 985 ++++++++++++++++++++++ Documentation/nvme-fw-activate.html | 884 ++++++++++++++++++++ Documentation/nvme-fw-download.html | 861 +++++++++++++++++++ Documentation/nvme-fw-log.html | 831 +++++++++++++++++++ Documentation/nvme-get-feature.html | 955 +++++++++++++++++++++ Documentation/nvme-get-log.html | 876 ++++++++++++++++++++ Documentation/nvme-get-ns-id.html | 803 ++++++++++++++++++ Documentation/nvme-help.html | 803 ++++++++++++++++++ Documentation/nvme-id-ctrl.html | 906 ++++++++++++++++++++ Documentation/nvme-id-ns.html | 936 +++++++++++++++++++++ Documentation/nvme-io-passthru.html | 955 +++++++++++++++++++++ Documentation/nvme-list-ns.html | 811 ++++++++++++++++++ Documentation/nvme-list.html | 793 ++++++++++++++++++ Documentation/nvme-read.html | 828 +++++++++++++++++++ Documentation/nvme-resv-acquire.html | 952 +++++++++++++++++++++ Documentation/nvme-resv-register.html | 941 +++++++++++++++++++++ Documentation/nvme-resv-release.html | 935 +++++++++++++++++++++ Documentation/nvme-resv-report.html | 838 +++++++++++++++++++ Documentation/nvme-security-recv.html | 869 ++++++++++++++++++++ Documentation/nvme-security-send.html | 855 +++++++++++++++++++ Documentation/nvme-set-feature.html | 919 +++++++++++++++++++++ Documentation/nvme-show-regs.html | 802 ++++++++++++++++++ Documentation/nvme-smart-log.html | 846 +++++++++++++++++++ Documentation/nvme-write.html | 828 +++++++++++++++++++ Documentation/nvme.1 | 150 +++- Documentation/nvme.html | 1047 ++++++++++++++++++++++++ Documentation/nvme.txt | 8 + 37 files changed, 25977 insertions(+), 18 deletions(-) create mode 100644 Documentation/asciidoc.conf create mode 100644 Documentation/cmds-main.txt create mode 100755 Documentation/install-webdoc.sh create mode 100644 Documentation/nvme-admin-passthru.html create mode 100644 Documentation/nvme-compare.html create mode 100644 Documentation/nvme-error-log.html create mode 100644 Documentation/nvme-flush.html create mode 100644 Documentation/nvme-format.html create mode 100644 Documentation/nvme-fw-activate.html create mode 100644 Documentation/nvme-fw-download.html create mode 100644 Documentation/nvme-fw-log.html create mode 100644 Documentation/nvme-get-feature.html create mode 100644 Documentation/nvme-get-log.html create mode 100644 Documentation/nvme-get-ns-id.html create mode 100644 Documentation/nvme-help.html create mode 100644 Documentation/nvme-id-ctrl.html create mode 100644 Documentation/nvme-id-ns.html create mode 100644 Documentation/nvme-io-passthru.html create mode 100644 Documentation/nvme-list-ns.html create mode 100644 Documentation/nvme-list.html create mode 100644 Documentation/nvme-read.html create mode 100644 Documentation/nvme-resv-acquire.html create mode 100644 Documentation/nvme-resv-register.html create mode 100644 Documentation/nvme-resv-release.html create mode 100644 Documentation/nvme-resv-report.html create mode 100644 Documentation/nvme-security-recv.html create mode 100644 Documentation/nvme-security-send.html create mode 100644 Documentation/nvme-set-feature.html create mode 100644 Documentation/nvme-show-regs.html create mode 100644 Documentation/nvme-smart-log.html create mode 100644 Documentation/nvme-write.html create mode 100644 Documentation/nvme.html diff --git a/Documentation/Makefile b/Documentation/Makefile index 353e60f3..6c4c9e6e 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -10,11 +10,15 @@ MAN1_TXT += $(filter-out \ MAN1_TXT += nvme.txt MAN_TXT = $(MAN1_TXT) MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT)) +MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT)) + +DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML) API_DOCS = SP_ARTICLES += $(API_DOCS) SP_ARTICLES += $(TECH_DOCS) + DOC_MAN1 = $(patsubst %.txt,%.1,$(MAN1_TXT)) ASCIIDOC = asciidoc @@ -29,6 +33,11 @@ INSTALL ?= install RM ?= rm -f MAN_REPO = ../../nvme-manpages +ASCIIDOC_HTML = xhtml11 +ASCIIDOC_CONF = -f asciidoc.conf +ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) +TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) + MAKEINFO = makeinfo INSTALL_INFO = install-info DOCBOOK2X_TEXI = docbook2x-texi @@ -81,12 +90,17 @@ else # "make -w" NO_SUBDIR = : endif -all: man +all: man html + +html: $(DOC_HTML) man: man1 man1: $(DOC_MAN1) -install: install-man +install: install-man install-html + +install-html: html + '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir) install-man: man $(INSTALL) -d -m 755 /usr/local/man/man1 @@ -120,7 +134,7 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) date >$@ clean: - $(RM) *.xml *.xml+ *.html *.html+ + $(RM) *.xml *.xml+ *.html+ $(RM) *.texi *.texi+ *.texi++ nvme.info nvmeman.info $(RM) *.pdf $(RM) howto-index.txt howto/*.html doc.dep @@ -188,8 +202,19 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt) WEBDOC_DEST = /pub/software/scm/nvme/docs +$(MAN_HTML): %.html : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(TXT_TO_HTML) -d manpage -o $@+ $< && \ + mv $@+ $@ + quick-install: quick-install-man +$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt + +install-webdoc : html + '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST) + require-manrepo:: @if test ! -d $(MAN_REPO); \ then echo "nvme-manpages repository must exist at $(MAN_REPO)"; exit 1; fi diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf new file mode 100644 index 00000000..83008bc7 --- /dev/null +++ b/Documentation/asciidoc.conf @@ -0,0 +1,97 @@ +## linknvme: macro +# +# Usage: linknvme:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show Git link as: (
); if section is defined, else just show +# the command. + +[macros] +(?su)[\\]?(?Plinknvme):(?P\S*?)\[(?P.*?)\]= + +[attributes] +asterisk=* +plus=+ +caret=^ +startsb=[ +endsb=] +backslash=\ +tilde=~ +apostrophe=' +backtick=` +litdd=-- + +ifdef::backend-docbook[] +[linknvme-inlinemacro] +{0%{target}} +{0#} +{0#{target}{0}} +{0#} +endif::backend-docbook[] + +ifdef::backend-docbook[] +ifndef::git-asciidoc-no-roff[] +# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. +# v1.72 breaks with this because it replaces dots not in roff requests. +[listingblock] +{title} + +ifdef::doctype-manpage[] + .ft C +endif::doctype-manpage[] +| +ifdef::doctype-manpage[] + .ft +endif::doctype-manpage[] + +{title#} +endif::git-asciidoc-no-roff[] + +ifdef::git-asciidoc-no-roff[] +ifdef::doctype-manpage[] +# The following two small workarounds insert a simple paragraph after screen +[listingblock] +{title} + +| + +{title#} + +[verseblock] +{title} +{title%} +{title#} +| + +{title#} +{title%} +endif::doctype-manpage[] +endif::git-asciidoc-no-roff[] +endif::backend-docbook[] + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +Git +{git_version} +Git Manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] + +ifdef::backend-xhtml11[] +[attributes] +git-relative-html-prefix= +[linknvme-inlinemacro] +{target}{0?({0})} +endif::backend-xhtml11[] diff --git a/Documentation/cmds-main.txt b/Documentation/cmds-main.txt new file mode 100644 index 00000000..d313e6a1 --- /dev/null +++ b/Documentation/cmds-main.txt @@ -0,0 +1,84 @@ +linknvme:nvme-admin-passthru[1]:: + Admin Passthrough Comand + +linknvme:nvme-compare[1]:: + IO Compare + +linknvme:nvme-error-log[1]:: + Retrieve error logs + +linknvme:nvme-flush[1]:: + Submit flush + +linknvme:nvme-format[1]:: + Format namespace(s) + +linknvme:nvme-fw-activate[1]:: + F/W Activate + +linknvme:nvme-fw-download[1]:: + F/W Download + +linknvme:nvme-fw-log[1]:: + Retrieve f/w log + +linknvme:nvme-get-feature[1]:: + Get Features + +linknvme:nvme-get-log[1]:: + Generic Get Log + +linknvme:nvme-smart-log[1]:: + Retrieve Smart Log + +linknvme:nvme-get-ns-id[1]:: + Retrieve namespace identifier + +linknvme:nvme-help[1]:: + NVMe CLI Help + +linknvme:nvme-id-ctrl[1]:: + Identify Controller + +linknvme:nvme-id-ns[1]:: + Identify Namespace + +linknvme:nvme-io-passthru[1]:: + IO Passthrough Command + +linknvme:nvme-list-ns[1]:: + List all nvme namespaces + +linknvme:nvme-list[1]:: + List all nvme controllers + +linknvme:nvme-read[1]:: + Issue IO Read Command + +linknvme:nvme-write[1]:: + Issue IO Write Command + +linknvme:nvme-resv-acquire[1]:: + Acquire Namespace Reservation + +linknvme:nvme-resv-register[1]:: + Register Namespace Reservation + +linknvme:nvme-resv-release[1]:: + Release Namespace Reservation + +linknvme:nvme-resv-report[1]:: + Report Reservation Capabilities + +linknvme:nvme-security-recv[1]:: + Security Receive + +linknvme:nvme-security-send[1]:: + Security Send + +linknvme:nvme-set-feature[1]:: + Set Feature + +linknvme:nvme-show-regs[1]:: + Show NVMe Controller Registers + diff --git a/Documentation/install-webdoc.sh b/Documentation/install-webdoc.sh new file mode 100755 index 00000000..ed8b4ff3 --- /dev/null +++ b/Documentation/install-webdoc.sh @@ -0,0 +1,39 @@ +#!/bin/sh + +T="$1" + +for h in \ + *.txt *.html \ + howto/*.txt howto/*.html \ + technical/*.txt technical/*.html \ + RelNotes/*.txt *.css +do + if test ! -f "$h" + then + : did not match + elif test -f "$T/$h" && + $DIFF -u -I'^Last updated ' "$T/$h" "$h" + then + :; # up to date + else + echo >&2 "# install $h $T/$h" + rm -f "$T/$h" + mkdir -p $(dirname "$T/$h") + cp "$h" "$T/$h" + fi +done +strip_leading=$(echo "$T/" | sed -e 's|.|.|g') +for th in \ + "$T"/*.html "$T"/*.txt \ + "$T"/howto/*.txt "$T"/howto/*.html \ + "$T"/technical/*.txt "$T"/technical/*.html +do + h=$(expr "$th" : "$strip_leading"'\(.*\)') + case "$h" in + RelNotes-*.txt | index.html) continue ;; + esac + test -f "$h" && continue + echo >&2 "# rm -f $th" + rm -f "$th" +done +ln -sf git.html "$T/index.html" diff --git a/Documentation/nvme-admin-passthru.1 b/Documentation/nvme-admin-passthru.1 index b18b2fa0..5612a2e4 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.76.1 -.\" Date: 02/02/2015 -.\" Manual: \ \& -.\" Source: \ \& +.\" Date: 05/29/2015 +.\" Manual: Git Manual +.\" Source: Git .\" Language: English .\" -.TH "NVME\-ADMIN\-PASSTHR" "1" "02/02/2015" "\ \&" "\ \&" +.TH "NVME\-ADMIN\-PASSTHR" "1" "05/29/2015" "Git" "Git Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -110,13 +110,55 @@ Print the raw returned buffer to stdout if the command returns a structure\&. .RE .SH "EXAMPLES" .sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} The following will run the admin command with opcode=6 and cdw10=1, which cooresponds to an identify controller command\&. This example requires the data\-len param be 4096, which is the size of the returned structure\&. The \-r option is used because it is a data\-in command .sp +.if n \{\ +.RS 4 +.\} +.nf + +\&.ft C # nvme admin\-passthru /dev/nvme0 \-\-opcode=06 \-\-data\-len=4096 \-\-cdw10=1 \-r +\&.ft + +.fi +.if n \{\ +.RE +.\} +.RE .sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} Or if you want to save that structure to a file: .sp +.if n \{\ +.RS 4 +.\} +.nf + +\&.ft C # nvme admin\-passthru /dev/nvme0 \-\-opcode=06 \-\-data\-len=4096 \-\-cdw10=1 \-r \-b > id_ns\&.raw +\&.ft + +.fi +.if n \{\ +.RE +.\} +.RE .SH "NVME" .sp Part of the nvme\-user suite diff --git a/Documentation/nvme-admin-passthru.html b/Documentation/nvme-admin-passthru.html new file mode 100644 index 00000000..68f0e50b --- /dev/null +++ b/Documentation/nvme-admin-passthru.html @@ -0,0 +1,969 @@ + + + + + +nvme-admin-passthru(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme-admin-passthru <device> [--opcode=<opcode> | -o <opcode>]
+                [--flags=<flags> | -f <flags>] [-rsvd=<rsvd> | -R <rsvd>]
+                [--namespace-id=<nsid>] [--cdw2=<cdw2>] [--cdw3=<cdw3>]
+                [--cdw10=<cdw10>] [--cdw11=<cdw11>] [--cdw12=<cdw12>]
+                [--cdw13=<cdw13>] [--cdw14=<cdw14>] [--cdw15=<cdw15>]
+                [--data-len=<data-len> | -l <data-len>]
+                [--metadata-len=<len> | -m <len>]
+                [--input-file=<file> | -f <file>]
+                [--read | -r ] [--write | -w]
+                [--timeout=<to> | -t <to>]
+                [--show-command | --dry-run | -s]
+                [--raw-binary | -b]
+
+
+
+
+
+

DESCRIPTION

+
+

Submits an arbitrary NVMe admin command and returns the applicable +results. This may be the simply the commands result and status, or may +also include a buffer if the command returns one. This command does no +interpretation of the opcodes or options.

+

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 structure (if applicable) may be returned in +one of several ways depending on the option flags; the structure may +printed by the program as a hex dump, or may be returned as a raw buffer +printed to stdout for another program to parse.

+
+
+
+

OPTIONS

+
+
+
+-o <opcode> +
+
+--opcode=<opcode> +
+
+

+ The NVMe opcode to send to the device in the command +

+
+
+-f <flags> +
+
+--flags=<flags> +
+
+

+ The NVMe command flags to send to the device in the command +

+
+
+-R <rsvd> +
+
+--rsvd=<rsvd> +
+
+

+ The value for the reserved field in the command. +

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

+ The value for the ns-id in the command. +

+
+
+--cdw[2-3,10-15]=<cdw> +
+
+

+ Specifies the command dword value for that specified entry in + the command +

+
+
+-r +
+
+--read +
+
+-w +
+
+--write +
+
+

+ Used for the data-direction for the command and required for + commands sending/receiving data. Don’t use both read and write + at the same time. +

+
+
+-i <file> +
+
+--input-file=<file> +
+
+

+ If the command is a data-out (write) command, use this file + to fill the buffer sent to the device. If no file is given, + assumed to use STDIN. +

+
+
+-l <data-len> +
+
+--data-len=<data-len> +
+
+

+ The data length for the buffer used for this command. +

+
+
+-m <data-len> +
+
+--metadata-len=<data-len> +
+
+

+ The metadata length for the buffer used for this command. +

+
+
+-s +
+
+--show-cmd +
+
+--dry-run +
+
+

+ Do not actually send the command; print out the command that + would be sent. +

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

+ Print the raw returned buffer to stdout if the command returns + a structure. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +The following will run the admin command with opcode=6 and cdw10=1, which + cooresponds to an identify controller command. This example requires the + data-len param be 4096, which is the size of the returned structure. The -r + option is used because it is a data-in command +

    +
    +
    +
    # nvme admin-passthru /dev/nvme0 --opcode=06 --data-len=4096 --cdw10=1 -r
    +
    +
    • +
  • +

    +Or if you want to save that structure to a file: +

    +
    +
    +
    # nvme admin-passthru /dev/nvme0 --opcode=06 --data-len=4096 --cdw10=1 -r -b > id_ns.raw
    +
    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-admin-passthru.txt b/Documentation/nvme-admin-passthru.txt index 0becea35..c0b58960 100644 --- a/Documentation/nvme-admin-passthru.txt +++ b/Documentation/nvme-admin-passthru.txt @@ -93,16 +93,21 @@ OPTIONS EXAMPLES -------- -The following will run the admin command with opcode=6 and cdw10=1, which cooresponds -to an identify controller command. This example requires the data-len param be 4096, which -is the size of the returned structure. The -r option is used because it is a data-in command - +* The following will run the admin command with opcode=6 and cdw10=1, which + cooresponds to an identify controller command. This example requires the + data-len param be 4096, which is the size of the returned structure. The -r + option is used because it is a data-in command ++ +------------ # nvme admin-passthru /dev/nvme0 --opcode=06 --data-len=4096 --cdw10=1 -r +------------ ++ -Or if you want to save that structure to a file: - +* Or if you want to save that structure to a file: ++ +------------ # nvme admin-passthru /dev/nvme0 --opcode=06 --data-len=4096 --cdw10=1 -r -b > id_ns.raw - +------------ NVME ---- diff --git a/Documentation/nvme-compare.html b/Documentation/nvme-compare.html new file mode 100644 index 00000000..57753a0c --- /dev/null +++ b/Documentation/nvme-compare.html @@ -0,0 +1,819 @@ + + + + + +nvme-compare(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme-compare <device> [--start-block=<slba> | -s <slba>]
+                        [--block-count=<nlb> | -c <nlb>]
+                        [--data-size=<size> | -z <size>]
+                        [--ref-tag=<reftag> | -r <reftag>]
+                        [--data=<data-file> | -d <data-file>]
+                        [--prinfo=<prinfo> | -p <prinfo>]
+                        [--app-tag-mask=<appmask> | -m <appmask>]
+                        [--app-tag=<apptag> | -a <apptag>]
+                        [--limited-retry | -l]
+                        [--force-unit-access | -f]
+
+
+
+
+
+

DESCRIPTION

+
+

The Compare command reads the logical blocks specified by the command +from the medium and compares the data read to a comparison data buffer +transferred as part of the command. If the data read from the controller +and the comparison data buffer are equivalent with no miscompares, +then the command completes successfully. If there is any miscompare, +the command completes with an error of Compare Failure. If metadata is +provided, then a comparison is also performed for the metadata.

+
+
+
+

OPTIONS

+
+
+
+--start-block=<slba> +
+
+-s <slba> +
+
+

+ Start block. +

+
+
+
+
+
+

EXAMPLES

+
+

No examples yet.

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-error-log.html b/Documentation/nvme-error-log.html new file mode 100644 index 00000000..548a8d84 --- /dev/null +++ b/Documentation/nvme-error-log.html @@ -0,0 +1,861 @@ + + + + + +nvme-error-log(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme error-log <device>  [--namespace-id=<nsid> | -n <nsid>]
+                         [--log-entries=<entries> | -e <entries>]
+                         [--raw-binary | -b]
+
+
+
+
+
+

DESCRIPTION

+
+

Retrieves NVMe Error 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 error log structure may be returned in one of +several ways depending on the option flags; the structure may parsed by +the program and printed in a readable format or the raw buffer may be +printed to stdout for another program to parse.

+
+
+
+

OPTIONS

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

+ Retrieve the Error Log for the given nsid. This is optional + and its success may depend on the device’s capabilities to + provide this log on a per-namespace basis (see the NVMe Identify + Controller for this capability). The defualt nsid to use is + 0xffffffff for the device global error log. +

+
+
+-e <entries> +
+
+--log-entries=<entries> +
+
+

+ Specifies how many log entries the program should request from + the device. This must be at least one, and shouldn’t exceed the + device’s capabilities. Defaults to 64 log entries. +

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

+ Print the raw error log buffer to stdout. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Get the error log and print it in a human readable format: +

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

    +Print the raw output to a file: +

    +
    +
    +
    # nvme error-log /dev/nvme0 --raw-binary > error_log.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-flush.html b/Documentation/nvme-flush.html new file mode 100644 index 00000000..40224090 --- /dev/null +++ b/Documentation/nvme-flush.html @@ -0,0 +1,809 @@ + + + + + +nvme-flush(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme flush <device> [--namespace-id=<nsid> | -n <nsid>]
+
+
+
+
+
+

DESCRIPTION

+
+

The Flush command shall commit data and metadata associated with the +specified namespace(s) to nonvolatile media. The flush applies to +all commands completed prior to the submission of the Flush command. +The controller may also flush additional data and/or metadata from +any namespace.

+
+
+
+

OPTIONS

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

+ Specify the optional namespace id for this command. Defaults to + 0xffffffff, indicating flush for all namespaces. +

+
+
+
+
+
+

EXAMPLES

+
+

No examples yet.

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-format.html b/Documentation/nvme-format.html new file mode 100644 index 00000000..3fb9656a --- /dev/null +++ b/Documentation/nvme-format.html @@ -0,0 +1,985 @@ + + + + + +nvme-format(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme format <device> [--namespace-id=<nsid> | -n <nsid>]
+                    [--lbaf=<lbaf> | -l <lbaf>]
+                    [--ses=<ses> | -s <ses>]
+                    [--pil=<pil> | -p <pil>]
+                    [--pi=<pi> | -i <pi>]
+                    [--ms=<ms> | -m <ms>]
+
+
+
+
+
+

DESCRIPTION

+
+

For the NVMe device given, send an nvme Format Namespace admin command +and provides the results.

+

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 identifer will default +to 0xffffffff to send the format to all namespace, but can be overridden +to any namespace with the namespace-id option. If the block device +is given, the namespace identifier will default to the namespace id of +the block device given, but can be overriden with the same option.

+

On success, the program will automatically issue BLKRRPART ioctl to +force rescanning the namespaces. If the driver is recent enough, this +will automatically update the physical block size. If it is not recent +enough, you will need to remove and rescan your device some other way +for the new block size to be visible.

+
+
+
+

OPTIONS

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

+ Send the format command for the specified nsid. This can be + used to override the default value for either character device + (0xffffffff) or the block device (result from NVME_IOCTL_ID). +

+
+
+-l <lbaf> +
+
+--lbaf=<lbaf> +
+
+

+ LBA Format: This field specifies the LBA format to apply to the NVM + media. This corresponds to the LBA formats indicated in the + Identify Namespace command. Defaults to 0. +

+
+
+-s <ses> +
+
+--ses=<ses> +
+
+

+ Secure Erase Settings: This field specifies whether a secure + erase should be performed as part of the format and the type of + the secureerase operation. The erase applies to all user data, + regardless of location (e.g., within an exposed LBA, within a + cache, within deallocated LBAs, etc). Defaults to 0. +

+
+ +++ + + + + + + + + + + + + + + + + + + + + + +

Value

Definition

0

No secure erase operation requested

1

User Data Erase: All user data shall be erased, contents of the user +data after the erase is indeterminate (e.g., the user data may be zero +filled, one filled, etc). The controller may perform a cryptographic +erase when a User Data Erase is requested if all user data is encrypted.

2

Cryptographic Erase: All user data shall be erased +cryptographically. This is accomplished by deleting the encryption key.

3–7

Reserved

+
+
+
+-p <pil> +
+
+--pil=<pil> +
+
+

+ Protection Information Location: If set to ‘1’ and protection + information is enabled, then protection information is transferred + as the first eight bytes of metadata. If cleared to ‘0’ and + protection information is enabled, then protection information + is transferred as the last eight bytes of metadata. Defaults to 0. +

+
+
+-i <pi> +
+
+--pi=<pi> +
+
+

+ Protection Information: This field specifies whether end-to-end + data protection is enabled and the type of protection + information. Defaults to 0. +

+
+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + +

Value

Definition

0

Protection information is not enabled

1

Protection information is enabled, Type 1

2

Protection information is enabled, Type 2

3

Protection information is enabled, Type 3

4–7

Reserved

+
+
+
+-m <ms> +
+
+--ms=<ms> +
+
+

+ Metadata Settings: This field is set to ‘1’ if the metadata + is transferred as part of an extended data LBA. This field is + cleared to ‘0’ if the metadata is transferred as part of a + separate buffer. The metadata may include protection information, + based on the Protection Information (PI) field. Defaults to 0. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Format the device using all defaults: +

    +
    +
    +
    # nvme format /dev/nvme0n1
    +
    +
    • +
  • +

    +Format namespace 1 with user data secure erase settings and protection +information: +

    +
    +
    +
    # nvme format /dev/nvme0 --namespace-id=1 --ses=1 --pi=1
    +
    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-fw-activate.html b/Documentation/nvme-fw-activate.html new file mode 100644 index 00000000..4fad3fa8 --- /dev/null +++ b/Documentation/nvme-fw-activate.html @@ -0,0 +1,884 @@ + + + + + +nvme-fw-activate(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme fw-activate <device> [--slot=<slot> | -s <slot>]
+                    [--action=<action> | -a <action>]
+
+
+
+
+
+

DESCRIPTION

+
+

For the NVMe device given, send an nvme Firmware Activate admin command +and provides the results.

+

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 ‘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 +be determined from the Firmware Revision field of the Identify Controller +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 +reset through Linux sysfs, for example:

+
+
+
 # echo 1 > /sys/class/misc/nvme0/device/reset
+
+

If your kernel is not recent enough, you will need to remove and add +the device some other way.

+
+
+
+

OPTIONS

+
+
+
+-a <action> +
+
+--action=<action> +
+
+

+ 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. +

+
+ +++ + + + + + + + + + + + + + + + + + + + + + +

Value

Definition

0

Downloaded image replaces the image indicated by the Firmware Slot +field. This image is not activated.

1

Downloaded image replaces the image indicated by the Firmware Slot +field. This image is activated at the next reset.

2

The image indicated by the Firmware Slot field is activated at the +next reset.

3

Reserved.

+
+
+
+-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, + then the controller shall choose the firmware slot (slot 1 – 7) + to use for the operation. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Activate the last downloaded fw to slot 1. +

    +
    +
    +
    # nvme fw-activate /dev/nvme0 --slot=1 --action=2
    +
    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-fw-download.html b/Documentation/nvme-fw-download.html new file mode 100644 index 00000000..dcd961c1 --- /dev/null +++ b/Documentation/nvme-fw-download.html @@ -0,0 +1,861 @@ + + + + + +nvme-fw-download(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme fw-download <device> [--fw=<firmware-file> | -f <firmware-file>]
+                    [--xfer=<transfer-size> | -x <transfer-size>]
+                    [--offset=<offset> | -o <offset>]
+
+
+
+
+
+

DESCRIPTION

+
+

The Firmware Image Download command is used to download all or a portion +of the firmware image for a future update to the controller. The Firmware +Image Download command may be submitted while other commands on the Admin +Submission Queue or I/O Submission Queues are outstanding. The Firmware +Image Download command copies the new firmware image (in whole or in part) +to the controller.

+

The firmware image may be constructed of multiple pieces that +are individually downloaded with separate Firmware Image Download +commands. Each Firmware Image Download command includes a Dword +Offset and Number of Dwords that specify a Dword range. The host +software shall ensure that firmware pieces do not have Dword ranges +that overlap. Firmware portions may be submitted out of order to the +controller.

+

The new firmware image is not applied as part of the Firmware Image +Download command. It is applied following a reset, where the image to +apply and the firmware slot it should be committed to is specified with +the Firmware Activate command.

+
+
+
+

OPTIONS

+
+
+
+-f <firmware-file> +
+
+--fw=<firmeware-file> +
+
+

+ Required argument. This specifies the path to the device’s + firmware file on your system that will be read by the program + and sent to the device. +

+
+
+-x <transfer-size> +
+
+--xfer=<transfer-size> +
+
+

+ This specifies the size to split each transfer. This is useful if + the device has a max transfer size requirement for firmware. It + defaults to 4k. +

+
+
+-o <offset> +
+
+--offset=<offset> +
+
+

+ This specifies the starting offset in dwords. This is really only + useful if your firmware is split in multiple files; otherwise + the offset starts at zero and automatically adjusts based on the + xfer size given. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Transfer a firmware size 128KiB at a time: +

    +
    +
    +
    # nvme fw-download /dev/nvme0 --fw=/path/to/nvme.fw --xfer=0x20000
    +
    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-fw-log.html b/Documentation/nvme-fw-log.html new file mode 100644 index 00000000..2c17f4bf --- /dev/null +++ b/Documentation/nvme-fw-log.html @@ -0,0 +1,831 @@ + + + + + +nvme-fw-log(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme fw-log <device> [--raw-binary | -b]
+
+
+
+
+
+

DESCRIPTION

+
+

Retrieves the NVMe Firmware 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 f/w log structure may be returned in one of +several ways depending on the option flags; the structure may parsed by +the program and printed in a readable format or the raw buffer may be +printed to stdout for another program to parse.

+
+
+
+

OPTIONS

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

+ Print the raw fw log buffer to stdout. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Print the firmware log page in a human readable format: +

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

    +Print the log firmware to a file: +

    +
    +
    +
    # nvme fw-log /dev/nvme0 --raw-binary > fw_log.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-get-feature.html b/Documentation/nvme-get-feature.html new file mode 100644 index 00000000..1bd26981 --- /dev/null +++ b/Documentation/nvme-get-feature.html @@ -0,0 +1,955 @@ + + + + + +nvme-get-feature(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme get-feature <device> [--namespace-id=<nsid> | -n <nsid>]
+                          [--feature-id=<fid> | -f <fid>] [--cdw11=<cdw11>]
+                          [--data-len=<data-len> | -l <data-len>]
+                          [--sel=<select> | -s <select>]
+                          [--raw-binary | -b]
+
+
+
+
+
+

DESCRIPTION

+
+

Submits an NVMe Get Feature admin command and returns the applicable +results. This may be the feature’s value, or may also include a feature +structure if the feature requires it (ex: LBA Range Type).

+

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 feature’s structure (if applicable) may be +returned in one of several ways depending on the option flags; the +structure may parsed by the program and printed in a readable format +if it is a known structure, displayed in hex, or the raw buffer may be +printed to stdout for another program to parse.

+
+
+
+

OPTIONS

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

+ Retrieve the feature for the given nsid. This is optional and + most features do not use this value. +

+
+
+-f <fid> +
+
+--feature-id=<fid> +
+
+

+ The feature id to send with the command. Value provided should + be in hex. +

+
+
+-s <select> +
+
+--sel=<select> +
+
+

+ Select (SEL): This field specifies which value of the attributes + to return in the provided data: +

+
+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + +

Select

Description

0

Current

1

Default

2

Saved

3

Supported capabilities

4–7

Reserved

+
+
+
+-l <data-len> +
+
+--data-len=<data-len> +
+
+

+ The data length for the buffer returned for this feature. Most + known features do not use this value. The exception is LBA + Range Type +

+
+
+--cdw11=<cdw11> +
+
+

+ The value for command dword 11, if applicable. Only known feature + using this is the interrupt vector configuration feature. +

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

+ Print the raw feature buffer to stdout if the feature returns + a structure. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Retrieves the feature for Number of Queues, or feature id 7: +

    +
    +
    +
    # nvme get-feature /dev/nvme0 -f 7
    +
    +
    • +
  • +

    +The following retrieves the feature for the LBA Range Type, which +implicitly requires a buffer and will be printed to the screen in human +readable format: +

    +
    +
    +
    # nvme get-feature /dev/nvme0 -f 3
    +
    +
    • +
  • +

    +Retrieves the feature for the some vendor specific feature and +specifically requesting a buffer be allocate for this feature, which +will be displayed to the user in as a hex dump: +

    +
    +
    +
    # nvme get-feature /dev/nvme0 -f c0 -l 512
    +
    +
    • +
  • +

    +The following retrieves the feature for the LBA Range Type, which +implicitly requires a buffer and will be saved to a file in its raw +format: +

    +
    +
    +
    # nvme get-feature /dev/nvme0 -f 3 --raw-binary > lba_range.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-get-log.html b/Documentation/nvme-get-log.html new file mode 100644 index 00000000..1364f78f --- /dev/null +++ b/Documentation/nvme-get-log.html @@ -0,0 +1,876 @@ + + + + + +nvme-get-log(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme get-log <device> [--log-id=<log-id> | -i <log-id>]
+                      [--log-len=<log-len> | -l <log-len>]
+                      [--namespace-id=<nsid> | -n <nsid>]
+                      [--raw-binary | -b]
+
+
+
+
+
+

DESCRIPTION

+
+

Retrieves an arbitrary NVMe 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 may be returned in one of several +ways depending on the option flags; the structure may be displayed in +hex by the program or the raw buffer may be printed to stdout for another +program to parse.

+
+
+
+

OPTIONS

+
+
+
+-l <log-len> +
+
+--log-len=<log-len> +
+
+

+ Allocates a buffer of <log-len> bytes size and requests this + many bytes be returned in the constructed NVMe command. This + param is mandatory. +

+
+
+-i <log-id> +
+
+--log-id=<log-id> +
+
+

+ Sets the commands requested log-id to <log-id>. Defaults to 0. +

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

+ Sets the command’s nsid value to the given nsid. Defaults to + 0xffffffff if not given. This option may not affect anything + depending on the log page, which may or may not be specific to + a namespace. +

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

+ Print the raw log buffer to stdout. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Get 512 bytes from log page 2 +

    +
    +
    +
    # nvme get-log /dev/nvme0 --log-id=2 --log-len=512
    +
    +

    The above example will get log page 2 (SMART), and request 512 +bytes. On success, the returned log will be dumped in hex and not +interpreted by the program.

    +
    • +
  • +

    +Have the program return the raw log page in binary: +

    +
    +
    +
    # nvme get-log /dev/nvme0 -log-id=2 --log-len=512 --raw-binary > log_page_2.raw
+# nvme get-log /dev/nvme0 -i 2 -l 512 -b > log_page_2.raw
    +
    +

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

    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-get-ns-id.html b/Documentation/nvme-get-ns-id.html new file mode 100644 index 00000000..f4c762c4 --- /dev/null +++ b/Documentation/nvme-get-ns-id.html @@ -0,0 +1,803 @@ + + + + + +nvme-get-ns-id(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme get-ns-id <device>
+
+
+
+
+
+

DESCRIPTION

+
+

Retrieves the namespace ID for an NVMe block device. The <device> param +is mandatory and must be an NVMe block device (ex: /dev/nvme0n1).

+
+
+
+

OPTIONS

+
+

None

+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Shows the namespace id for the given block device: +

    +
    +
    +
    # nvme get-ns-id /dev/nvme0n1
    +
    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-help.html b/Documentation/nvme-help.html new file mode 100644 index 00000000..f46ca644 --- /dev/null +++ b/Documentation/nvme-help.html @@ -0,0 +1,803 @@ + + + + + +nvme-help(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme help [<command>]
+
+
+
+
+
+

DESCRIPTION

+
+

Provides help information, with detailed information about the given command if provided.

+
+
+
+

OPTIONS

+
+

No Options

+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Show help for nvme smart log: +

    +
    +
    +
    # nvme help smart-log
    +
    +

    Not much to it

    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-id-ctrl.html b/Documentation/nvme-id-ctrl.html new file mode 100644 index 00000000..0c5f027a --- /dev/null +++ b/Documentation/nvme-id-ctrl.html @@ -0,0 +1,906 @@ + + + + + +nvme-id-ctrl(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme id-ctrl <device> [-v | --vendor-specific] [-b | --raw-binary]
+
+
+
+
+
+

DESCRIPTION

+
+

For the NVMe device given, sends an identify controller 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).

+

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

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

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

+
+
+-v +
+
+--vendor-specific +
+
+

+ In addition to parsing known fields, this option will dump + the vendor specific region of the structure in hex with ascii + interpretation. +

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

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

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Has the program interpret the returned buffer and display the known +fields in a human readable format: +

    +
    +
    +
    # nvme id-ctrl /dev/nvme0
    +
    +
    • +
  • +

    +In addition to showing the known fields, has the program to display +the vendor unique field: +

    +
    +
    +
    # nvme id-ctrl /dev/nvme0 --vendor-specific
+# nvme id-ctrl /dev/nvme0 -v
    +
    +

    The above will dump the vs buffer in hex since it doesn’t know how to +interpret it.

    +
    • +
  • +

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

    +
    +
    +
    # nvme id-ctrl /dev/nvme0 --raw-binary > id_ctrl.raw
+# nvme id-ctrl /dev/nvme0 -b > id_ctrl.raw
    +
    +

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

    +
    • +
  • +

    +Alternatively you may want to send the data to another program that +can parse the raw buffer. +

    +
    +
    +
    # nvme id-ctrl /dev/nvme0 --raw-binary | nvme_parse_id_ctrl
    +
    +

    The parse program in the above example can be a program that shows the +structure in a way you like. The following program is such an example +that will parse it and can accept the output through a pipe, '|', +as shown in the above example, or you can 'cat' a saved output buffer to it.

    +
    • +
+
+
+
/* File: nvme_parse_id_ctrl.c */
+
+#include <linux/nvme.h>
+#include <stdio.h>
+#include <unistd.h>
+
+int main(int argc, char **argv)
+{
+        unsigned char buf[sizeof(struct nvme_id_ctrl)];
+        struct nvme_id_ctrl *ctrl = (struct nvme_id_ctrl *)buf;
+
+        if (read(STDIN_FILENO, buf, sizeof(buf)))
+                return 1;
+
+        printf("vid   : %#x\n", ctrl->vid);
+        printf("ssvid : %#x\n", ctrl->ssvid);
+        return 0;
+}
+
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-id-ns.html b/Documentation/nvme-id-ns.html new file mode 100644 index 00000000..7f9567a5 --- /dev/null +++ b/Documentation/nvme-id-ns.html @@ -0,0 +1,936 @@ + + + + + +nvme-id-ns(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme id-ns <device> [-v | --vendor-specific] [-b | --raw-binary]
+                    [--namespace-id=<nsid> | -n <nsid>]
+
+
+
+
+
+

DESCRIPTION

+
+

For the NVMe device given, sends an identify namespace 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 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. This overrides the vendor specific and human readable options. +

+
+
+-v +
+
+--vendor-specific +
+
+

+ In addition to parsing known fields, this option will dump + the vendor specific region of the structure in hex with ascii + interpretation. +

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

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

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Has the program interpret the returned buffer and display the known +fields in a human readable format: +

    +
    +
    +
    # nvme id-ns /dev/nvme0n1
    +
    +
    • +
  • +

    +If using the character device or overriding namespace id: +

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

    +In addition to showing the known fields, have the program to display +the vendor unique field: +

    +
    +
    +
    # nvme id-ns /dev/nvme0n1 --vendor-specific
+# nvme id-ns /dev/nvme0n1 -v
    +
    +

    The above will dump the 'vs' buffer in hex since it doesn’t know how to +interpret it.

    +
    • +
  • +

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

    +
    +
    +
    # nvme id-ns /dev/nvme0n1 --raw-binary > id_ns.raw
+# nvme id-ns /dev/nvme0n1 -b > id_ns.raw
    +
    +

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

    +
    • +
  • +

    +Alternatively you may want to send the data to another program that +can parse the raw buffer. +

    +
    +
    +
    # nvme id-ns /dev/nvme0n1 --raw-binary | nvme_parse_id_ns
    +
    +

    The parse program in the above example can be a program that shows the +structure in a way you like. The following program is such an example +that will parse it and can accept the output through a pipe, '|', +as shown in the above example, or you can 'cat' a saved output buffer +to it.

    +
    • +
+
+
+
/* File: nvme_parse_id_ns.c */
+
+#include <linux/nvme.h>
+#include <stdio.h>
+#include <unistd.h>
+
+int main(int argc, char **argv)
+{
+        unsigned char buf[sizeof(struct nvme_id_ns)];
+        struct nvme_id_ns *ns = (struct nvme_id_ns *)buf;
+
+        if (read(STDIN_FILENO, buf, sizeof(buf)))
+                return 1;
+
+        printf("nsze : %#llx\n", ns->nsze);
+        printf("ncap : %#llx\n", ns->ncap);
+        return 0;
+}
+
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-io-passthru.html b/Documentation/nvme-io-passthru.html new file mode 100644 index 00000000..b47f4bfb --- /dev/null +++ b/Documentation/nvme-io-passthru.html @@ -0,0 +1,955 @@ + + + + + +nvme-io-passthru(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme-io-passthru <device> [--opcode=<opcode> | -o <opcode>]
+                [--flags=<flags> | -f <flags>] [-rsvd=<rsvd> | -R <rsvd>]
+                [--namespace-id=<nsid> | -nsid <nsid>]
+                [--cdw2=<cdw2>] [--cdw3=<cdw3>] [--cdw10=<cdw10>]
+                [--cdw11=<cdw11>] [--cdw12=<cdw12>] [--cdw13=<cdw13>]
+                [--cdw14=<cdw14>] [--cdw15=<cdw15>]
+                [--data-len=<data-len> | -l <data-len>]
+                [--metadata-len=<len> | -m <len>]
+                [--read | -r ] [--write | -w]
+                [--input-file=<file> | -f <file>]
+                [--timeout=<to> | -t <to>]
+                [--show-command | --dry-run | -s]
+                [--raw-binary | -b]
+
+
+
+
+
+

DESCRIPTION

+
+

Submits an arbitrary NVMe IO command and returns the applicable +results. This may be the simply the command’s result and status, or may +also include a buffer if the command returns one. This command does no +interpretation of the opcodes or options.

+

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 structure (if applicable) may be returned in +one of several ways depending on the option flags; the structure may +printed by the program as a hex dump, or may be returned as a raw buffer +printed to stdout for another program to parse.

+
+
+
+

OPTIONS

+
+
+
+-o <opcode> +
+
+--opcode=<opcode> +
+
+

+ The NVMe opcode to send to the device in the command +

+
+
+-f <flags> +
+
+--flags=<flags> +
+
+

+ The NVMe command flags to send to the device in the command +

+
+
+-R <rsvd> +
+
+--rsvd=<rsvd> +
+
+

+ The value for the reserved field in the command. +

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

+ The value for the ns-id in the command. Defaults to 0. +

+
+
+--cdw[2-3,10-15]=<cdw> +
+
+

+ Specifies the command dword value for that specified entry in + the command +

+
+
+-r +
+
+--read +
+
+-w +
+
+--write +
+
+

+ Used for the data-direction for the command and required for + commands sending/receiving data. Don’t use both read and write + at the same time. +

+
+
+-i <file> +
+
+--input-file=<file> +
+
+

+ If the command is a data-out (write) command, use this file + to fill the buffer sent to the device. If no file is given, + assumed to use STDIN. +

+
+
+-l <data-len> +
+
+--data-len=<data-len> +
+
+

+ The data length for the buffer used for this command. +

+
+
+-m <data-len> +
+
+--metadata-len=<data-len> +
+
+

+ The metadata length for the buffer used for this command. +

+
+
+-s +
+
+--show-cmd +
+
+

+ Print out the command to be sent. +

+
+
+-d +
+
+--dry-run +
+
+

+ Do not actually send the command. +

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

+ Print the raw returned buffer to stdout if the command returns + data or a structure. +

+
+
+
+
+
+

EXAMPLES

+
+

nvme io-passthru /dev/nvme0n1 --opcode=2 --namespace-id=1 --data-len=4096 --read --cdw10=0 --cdw11=0 --cdw12=0x70000 --raw-binary

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-list-ns.html b/Documentation/nvme-list-ns.html new file mode 100644 index 00000000..20556fea --- /dev/null +++ b/Documentation/nvme-list-ns.html @@ -0,0 +1,811 @@ + + + + + +nvme-id-ns(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme list-ns <device> [--namespace-id=<nsid> | -n <nsid>]
+
+
+
+
+
+

DESCRIPTION

+
+

For the NVMe device given, sends an identify command for namespace list +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 starting namespace in the list always begins with 0 unless the +'--namespace-id' option is given to override.

+

On success, the namespace array is printed for each index and nsid for +a valid nsid.

+
+
+
+

OPTIONS

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

+ Retrieve the identify list structure starting with the given nsid. +

+
+
+
+
+
+

EXAMPLES

+
+

No examples yet.

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-list.html b/Documentation/nvme-list.html new file mode 100644 index 00000000..816cd607 --- /dev/null +++ b/Documentation/nvme-list.html @@ -0,0 +1,793 @@ + + + + + +nvme-list(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme list
+
+
+
+
+
+

DESCRIPTION

+
+

Scan the sysfs tree for NVM Express devices and return the /dev node +for those devices as well as some pertinant information about them.

+
+
+
+

OPTIONS

+
+

No options yet.

+
+
+
+

EXAMPLES

+
+

No examples yet.

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-read.html b/Documentation/nvme-read.html new file mode 100644 index 00000000..4284cc17 --- /dev/null +++ b/Documentation/nvme-read.html @@ -0,0 +1,828 @@ + + + + + +nvme-compare(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme-read <device> [--start-block=<slba> | -s <slba>]
+                        [--block-count=<nlb> | -c <nlb>]
+                        [--data-size=<size> | -z <size>]
+                        [--metadata-size=<size> | -y <size>]
+                        [--ref-tag=<reftag> | -r <reftag>]
+                        [--data=<data-file> | -d <data-file>]
+                        [--prinfo=<prinfo> | -p <prinfo>]
+                        [--app-tag-mask=<appmask> | -m <appmask>]
+                        [--app-tag=<apptag> | -a <apptag>]
+                        [--limited-retry | -l]
+                        [--latency | -t]
+                        [--force-unit-access | -f]
+
+
+
+
+
+

DESCRIPTION

+
+

The Read command reads the logical blocks specified by the command from +the medium and copies to the data data buffer provided. Will use stdout +by default if you don’t provide a file.

+
+
+
+

OPTIONS

+
+
+
+--start-block=<slba> +
+
+-s <slba> +
+
+

+ Start block. +

+
+
+--latency +
+
+-t +
+
+

+ Print out the latency the IOCTL took (in us). +

+
+
+
+
+
+

EXAMPLES

+
+

No examples yet.

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-resv-acquire.html b/Documentation/nvme-resv-acquire.html new file mode 100644 index 00000000..0e5c852e --- /dev/null +++ b/Documentation/nvme-resv-acquire.html @@ -0,0 +1,952 @@ + + + + + +nvme-resv-acquire(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme resv-acquire <device>
+
+
+
+
+
+

DESCRIPTION

+
+

The Reservation Acquire command is used to acquire a reservation on +a namespace, preempt a reservation held on a namespace, and abort a +reservation held on a namespace.

+
+
+
+

OPTIONS

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

+ Override the nsid field. If using the admin character device, + this paramter is required. +

+
+
+-c <crkey> +
+
+--crkey=<crkey> +
+
+

+ Current Reservation Key: The field specifies the current + reservation key associated with the host. If the IEKEY bit is + set to ‘1’ in the command, then the CRKEY check succeeds + regardless of the value in this field. +

+
+
+-p <prkey> +
+
+--prkey=<prkey> +
+
+

+ Preempt Reservation Key: If the Reservation Acquire Action is set + to 001b (i.e., Preempt) or 010b (i.e., Preempt and Abort), then + this field specifies the reservation key to be unregistered from + the namespace. For all other Reservation Acquire Action values, + this field is reserved. +

+
+
+-t <rtype> +
+
+--rtyep=<rtype> +
+
+

+ Reservation Type: This field specifies the type of reservation + to be created. +

+
+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Value

Definition

0h

Reserved

1h

Write Exclusive Reservation

2h

Exclusive Access Reservation

3h

Write Exclusive - Registrants Only Reservation

4h

Exclusive Access - Registrants Only Reservation

5h

Write Exclusive - All Registrants Reservation

6h

Exclusive Access - All Registrants Reservation

07h-FFh

Reserved

+
+
+
+-a <racqa> +
+
+--racqa=<racqa> +
+
+

+ Reservation Acquire Action: This field specifies the action that + is performed by the command. +

+
+ +++ + + + + + + + + + + + + + + + + + + + + + +

Value

Definition

0

Acquire

1

Preempt

2

Preempt and Abort

3-7

Reserved

+
+
+
+-i +
+
+--iekey +
+
+

+ Ignore Existing Key: If this bit is set to a 1, then the + Current Reservation Key (CRKEY) check is disabled and the command + shall succeed regardless of the CRKEY field value. +

+

Indicator option, defaults to 0.

+
+
+
+
+
+

EXAMPLES

+
+

No examples yet

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-resv-register.html b/Documentation/nvme-resv-register.html new file mode 100644 index 00000000..03c3ba7e --- /dev/null +++ b/Documentation/nvme-resv-register.html @@ -0,0 +1,941 @@ + + + + + +nvme-resv-register(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme resv-register <device>
+
+
+
+
+
+

DESCRIPTION

+
+

The Reservation Register command is used to register, unregister, or +replace a reservation key.

+
+
+
+

OPTIONS

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

+ Override the nsid field. If using the admin character device, + this paramter is required. +

+
+
+-c <crkey> +
+
+--crkey=<crkey> +
+
+

+ Current Reservation Key: If the Reservation Register Action is + 001b (i.e., Unregister Reservation Key) or 010b (i.e., Replace + Reservation Key), then this field contains the current reservation + key associated with the host. For all other Reservation Register + Action values, this field is reserved. The controller ignores + the value of this field when the Ignore Existing Key (IEKEY) + bit is set to ‘1’. +

+
+
+-k <nrkey> +
+
+--nrkey=<nrkey> +
+
+

+ New Reservation Key: If the Reservation Register Action is + 000b (i.e., Register Reservation Key) or 010b (i.e., Replace + Reservation Key), then this field contains the new reservation + key associated with the host. For all other Reservation Register + Action values, this field is reserved. +

+
+
+-p <cptpl> +
+
+--cptpl=<cptpl> +
+
+

+ Change Persist Through Power Loss State: This field allows the + Persist Through Power Loss state associated with the namespace + to be modified as a side effect of processing this command. +

+
+ +++ + + + + + + + + + + + + + + + + + + + + + +

Value

Definition

0

No change to PTPL state

1

Reserved

2

Set PTPL state to ‘0’. Reservations are released and registrants +are cleared on a power on.

3

Set PTPL state to ‘1’. Reservations and registrants persist across +a power loss.

+
+
+
+-a <rrega> +
+
+--rrega=<rrega> +
+
+

+ Reservation Register Action: This field specifies the registration + action that is performed by the command. +

+
+ +++ + + + + + + + + + + + + + + + + + + + + + +

Value

Definition

0

Register Reservation Key

1

Unregister Reservation Key

2

Replace Reservation Key

3-7

Reserved

+
+
+
+-i +
+
+--iekey +
+
+

+ Ignore Existing Key: If this bit is set to a 1, then the + Current Reservation Key (CRKEY) check is disabled and the command + shall succeed regardless of the CRKEY field value. +

+

Indicator option, defaults to 0.

+
+
+
+
+
+

EXAMPLES

+
+

No examples yet

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-resv-release.html b/Documentation/nvme-resv-release.html new file mode 100644 index 00000000..0deaf236 --- /dev/null +++ b/Documentation/nvme-resv-release.html @@ -0,0 +1,935 @@ + + + + + +nvme-resv-release(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme resv-release <device>
+
+
+
+
+
+

DESCRIPTION

+
+

The Reservation Release command is used to release or clear a reservation +held on a namespace.

+
+
+
+

OPTIONS

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

+ Override the nsid field. If using the admin character device, + this paramter is required. +

+
+
+-c <crkey> +
+
+--crkey=<crkey> +
+
+

+ Current Reservation Key: If the Reservation Register Action is + 001b (i.e., Unregister Reservation Key) or 010b (i.e., Replace + Reservation Key), then this field contains the current reservation + key associated with the host. For all other Reservation Register + Action values, this field is reserved. The controller ignores + the value of this field when the Ignore Existing Key (IEKEY) + bit is set to ‘1’. +

+
+
+-t <rtype> +
+
+--rtyep=<rtype> +
+
+

+ Reservation Type: This field specifies the type of reservation + to be created. +

+
+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Value

Definition

0h

Reserved

1h

Write Exclusive Reservation

2h

Exclusive Access Reservation

3h

Write Exclusive - Registrants Only Reservation

4h

Exclusive Access - Registrants Only Reservation

5h

Write Exclusive - All Registrants Reservation

6h

Exclusive Access - All Registrants Reservation

07h-FFh

Reserved

+
+
+
+-a <rrela> +
+
+--rrela=<rrela> +
+
+

+ Reservation Release Action: This field specifies the registration + action that is performed by the command. +

+
+ +++ + + + + + + + + + + + + + + + + + +

Value

Definition

0

Release

1

Clear

2-7

Reserved

+
+
+
+-i +
+
+--iekey +
+
+

+ Ignore Existing Key: If this bit is set to a 1, then the + Current Reservation Key (CRKEY) check is disabled and the command + shall succeed regardless of the CRKEY field value. +

+

Indicator option, defaults to 0.

+
+
+
+
+
+

EXAMPLES

+
+

No examples yet

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-resv-report.html b/Documentation/nvme-resv-report.html new file mode 100644 index 00000000..9fd6348a --- /dev/null +++ b/Documentation/nvme-resv-report.html @@ -0,0 +1,838 @@ + + + + + +nvme-resv-report(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme resv-report <device> [--namespace-id=<nsid> | -n <nsid>]
+                        [--numd=<num-dwords> | -d <num-dwords>]
+                        [-b | --raw-binary]
+
+
+
+
+
+

DESCRIPTION

+
+

The Reservation Report command returns a Reservation Status data structure +to host memory that describes the registration and reservation status +of a namespace.

+

The size of the Reservation Status data structure is a function of the +number of controllers in the NVM Subsystem that are associated with +hosts that are registrants of the namespace (i.e., there is a Registered +Controller data structure for each such controller).

+
+
+
+

OPTIONS

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

+ Retrieve the reservation report structure for the given nsid. This + is required for the character devices, or overrides the block nsid + if given. +

+
+
+-d <num-dwords> +
+
+--numd=<num-dwords> +
+
+

+ Specify the number of Dwords of the Reservation Status structure + to transfer. Defaults to 4k. +

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

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

+
+
+
+
+
+

EXAMPLES

+
+

No examples yet.

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-security-recv.html b/Documentation/nvme-security-recv.html new file mode 100644 index 00000000..c1e8d729 --- /dev/null +++ b/Documentation/nvme-security-recv.html @@ -0,0 +1,869 @@ + + + + + +nvme-security-recv(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme security-recv [<device>] [--size=<size> | -x <size>]
+                    [--secp=<security-protocol> | -p <security-protocol>]
+                    [--spsp=<protocol-specific> | -s <protocol-specific>]
+                    [--tl=<transfer-length> | -t <transfer-length>]
+                    [-b | --raw-binary]
+
+
+
+
+
+

DESCRIPTION

+
+

The Security Receive command transfers the status and data result of +one or more Security Send commands that were previously submitted to +the controller.

+

The association between a Security Receive command and previous Security +Send commands is dependent on the Security Protocol. The format of the +data to be transferred is dependent on the Security Protocol. Refer to +SPC-4 for Security Protocol details.

+

Each Security Receive command returns the appropriate data corresponding +to a Security Send command as defined by the rules of the Security +Protocol. The Security Receive command data may not be retained if there +is a loss of communication between the controller and host, or if a +controller reset occurs.

+
+
+
+

OPTIONS

+
+
+
+-x <size> +
+
+--size=<size> +
+
+

+ Size of buffer to allocate. One success it will be printed + to STDOUT. +

+
+
+-p <security-protocol> +
+
+--secp=<security-protocol> +
+
+

+ Security Protocol: This field specifies the security protocol + as defined in SPC-4. The controller shall fail the command with + Invalid Parameter indicated if a reserved value of the Security + Protocol is specified. +

+
+
+-s <security-protocol-specific> +
+
+--spsp=<security-protocol-specific> +
+
+

+ SP Specific: The value of this field is specific to the Security + Protocol as defined in SPC-4. +

+
+
+-a <allocation-length> +
+
+--al=<allocation-length> +
+
+

+ Allocation Length: The value of this field is specific to the + Security Protocol as defined in SPC-4. +

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

+ Print the raw buffer to stdout. Defaults to print in hex. +

+
+
+
+
+
+

EXAMPLES

+
+

No Examples

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-security-send.html b/Documentation/nvme-security-send.html new file mode 100644 index 00000000..8096b704 --- /dev/null +++ b/Documentation/nvme-security-send.html @@ -0,0 +1,855 @@ + + + + + +nvme-security-send(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme security-send [<device>] [--file=<file> | -f <file>]
+                    [--secp=<security-protocol> | -p <security-protocol>]
+                    [--spsp=<protocol-specific> | -s <protocol-specific>]
+                    [--tl=<transfer-length> | -t <transfer-length>]
+
+
+
+
+
+

DESCRIPTION

+
+

The Security Send command is used to transfer security protocol data +to the controller. The data structure transferred to the controller +as part of this command contains security protocol specific commands +to be performed by the controller. The data structure transferred may +also contain data or parameters associated with the security protocol +commands. Status and data that is to be returned to the host for the +security protocol commands submitted by a Security Send command are +retrieved with the Security Receive command.

+

The association between a Security Send command and subsequent Security +Receive command is Security Protocol field dependent as defined in SPC-4.

+
+
+
+

OPTIONS

+
+
+
+-f <file> +
+
+--file=<file> +
+
+

+ Path to file used as the security protocol’s payload. Required + argument. +

+
+
+-p <security-protocol> +
+
+--secp=<security-protocol> +
+
+

+ Security Protocol: This field specifies the security protocol + as defined in SPC-4. The controller shall fail the command with + Invalid Parameter indicated if a reserved value of the Security + Protocol is specified. +

+
+
+-s <security-protocol-specific> +
+
+--spsp=<security-protocol-specific> +
+
+

+ SP Specific: The value of this field is specific to the Security + Protocol as defined in SPC-4. +

+
+
+-t <trans-length> +
+
+--tl=<trans-length> +
+
+

+ Transfer Length: The value of this field is specific to the + Security Protocol as defined in SPC-4. +

+
+
+
+
+
+

EXAMPLES

+
+

No Examples

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-set-feature.html b/Documentation/nvme-set-feature.html new file mode 100644 index 00000000..10817939 --- /dev/null +++ b/Documentation/nvme-set-feature.html @@ -0,0 +1,919 @@ + + + + + +nvme-set-feature(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme set-feature <device> [--namespace-id=<nsid> | -n <nsid>]
+                          [--feature-id=<fid> | -f <fid>] [--value=<value>]
+                          [--data-len=<data-len> | -l <data-len>]
+                          [--data=<data-file> | -d <data-file>]
+                          [--raw-binary | -b]
+
+
+
+
+
+

DESCRIPTION

+
+

Submits an NVMe Get Feature admin command and returns the applicable +results. This may be the feature’s value, or may also include a feature +structure if the feature requires it (ex: LBA Range Type).

+

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 feature’s structure (if applicable) may be +returned in one of several ways depending on the option flags; the +structure may parsed by the program and printed in a readable format +if it is a known structure, displayed in hex, or the raw buffer may be +printed to stdout for another program to parse.

+
+
+
+

OPTIONS

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

+ Retrieve the feature for the given nsid. This is optional and + most features do not use this value. +

+
+
+-f <fid> +
+
+--feature-id=<fid> +
+
+

+ The feature id to send with the command. Value provided should + be in hex. +

+
+
+-l <data-len> +
+
+--data-len=<data-len> +
+
+

+ The data length for the buffer submitted for this feature. Most + known features do not use this value. The exceptions are LBA + Range Type and host identifier. +

+
+
+-d <data-file> +
+
+--data=<data-file> +
+
+

+ The data file for the buffer submitted for this feature. Most + known features do not use this value. The exceptions is LBA + Range Type and host identifier. This defaults to STDIN so files + and echos can be piped. +

+
+
+--value=<value> +
+
+

+ The value for command dword 11, the value you want to set the + feature to. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Retrieves the feature for Number of Queues, or feature id 7: +

    +
    +
    +
    # nvme set-feature /dev/nvme0 -f 7
    +
    +
    • +
  • +

    +The following retrieves the feature for the LBA Range Type, which +implicitly requires a buffer and will be printed to the screen in human +readable format: +

    +
    +
    +
    # nvme set-feature /dev/nvme0 -f 3
    +
    +
    • +
  • +

    +Retrieves the feature for the some vendor specific feature and +specifically requesting a buffer be allocate for this feature, which +will be displayed to the user in as a hex dump: +

    +
    +
    +
    # nvme set-feature /dev/nvme0 -f c0 -l 512
    +
    +
    • +
  • +

    +Sets the host id to the ascii string. +

    +
    +
    +
    # echo "abcdefgh" | nvme set-feature /dev/nvme0 -f 0x81 -l 8
    +
    +
    • +
  • +

    +The following retrieves the feature for the LBA Range Type, which +implicitly requires a buffer and will be saved to a file in its raw +format: +

    +
    +
    +
    # nvme set-feature /dev/nvme0 -f 3 --raw-binary > lba_range.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-show-regs.html b/Documentation/nvme-show-regs.html new file mode 100644 index 00000000..dce63a10 --- /dev/null +++ b/Documentation/nvme-show-regs.html @@ -0,0 +1,802 @@ + + + + + +nvme-id-ns(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme show-regs <device>
+
+
+
+
+
+

DESCRIPTION

+
+

For the NVMe device given, sends an identify namespace command and +provides the result and returned structure.

+

The <device> parameter is mandatory and must be the nvme admin character +device (ex: /dev/nvme0). The program uses knowledge of the sysfs layout +to map the device to the pci resource stored there and mmaps the memory +to get access to the registers.

+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Has the program map the nvme pci controller registers and prints them +in a human readable format: +

    +
    +
    +
    # nvme show-regs /dev/nvme0
    +
    +
    • +
+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-smart-log.html b/Documentation/nvme-smart-log.html new file mode 100644 index 00000000..6b64a51b --- /dev/null +++ b/Documentation/nvme-smart-log.html @@ -0,0 +1,846 @@ + + + + + +nvme-smart-log(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme smart-log <device> [--namespace-id=<nsid> | -n <nsid>]
+                        [--raw-binary | -b]
+
+
+
+
+
+

DESCRIPTION

+
+

Retrieves the NVMe SMART 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 f/w log structure may be returned in one of +several ways depending on the option flags; the structure may parsed by +the program and printed in a readable format or the raw buffer may be +printed to stdout for another program to parse.

+
+
+
+

OPTIONS

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

+ Retrieve the SMART log for the given nsid. This is optional + and its success may depend on the device’s capabilities to + provide this log on a per-namespace basis (see the NVMe Identify + Controller for this capability). The defualt nsid to use is + 0xffffffff for the device global SMART log. +

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

+ Print the raw SMART log buffer to stdout. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Print the SMART log page in a human readable format: +

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

    +Print the raw SMART log to a file: +

    +
    +
    +
    # nvme smart-log /dev/nvme0 --raw-binary > fw_log.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-write.html b/Documentation/nvme-write.html new file mode 100644 index 00000000..e4067554 --- /dev/null +++ b/Documentation/nvme-write.html @@ -0,0 +1,828 @@ + + + + + +nvme-compare(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme-write <device> [--start-block=<slba> | -s <slba>]
+                        [--block-count=<nlb> | -c <nlb>]
+                        [--data-size=<size> | -z <size>]
+                        [--metadata-size=<size> | -y <size>]
+                        [--ref-tag=<reftag> | -r <reftag>]
+                        [--data=<data-file> | -d <data-file>]
+                        [--prinfo=<prinfo> | -p <prinfo>]
+                        [--app-tag-mask=<appmask> | -m <appmask>]
+                        [--app-tag=<apptag> | -a <apptag>]
+                        [--limited-retry | -l]
+                        [--latency | -t]
+                        [--force-unit-access | -f]
+
+
+
+
+
+

DESCRIPTION

+
+

The Write command writes the logical blocks specified by the command to +the medium from the data data buffer provided. Will use stdin by default +if you don’t provide a file.

+
+
+
+

OPTIONS

+
+
+
+--start-block=<slba> +
+
+-s <slba> +
+
+

+ Start block. +

+
+
+--latency +
+
+-t +
+
+

+ Print out the latency the IOCTL took (in us). +

+
+
+
+
+
+

EXAMPLES

+
+

No examples yet.

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme.1 b/Documentation/nvme.1 index c95c0e5e..ebaa03e5 100644 --- a/Documentation/nvme.1 +++ b/Documentation/nvme.1 @@ -2,12 +2,12 @@ .\" Title: nvme .\" Author: [see the "Authors" section] .\" Generator: DocBook XSL Stylesheets v1.76.1 -.\" Date: 02/09/2015 -.\" Manual: \ \& -.\" Source: \ \& +.\" Date: 05/29/2015 +.\" Manual: Git Manual +.\" Source: Git .\" Language: English .\" -.TH "NVME" "1" "02/09/2015" "\ \&" "\ \&" +.TH "NVME" "1" "05/29/2015" "Git" "Git Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -42,6 +42,148 @@ This \fInvme\fR program is a user space utility to provide standards compliant t .SH "NVME COMMANDS" .sp The utility has sub\-commands for all admin and io commands defined in the specification and for displaying controller registers\&. There is also an option to submit completely arbitrary commands\&. For a list of commands available, run "nvme help"\&. +.SH "NVME CLI SUB-COMMANDS" +.SS "Main commands" +.PP +linknvme:nvme\-admin\-passthru +.RS 4 +Admin Passthrough Comand +.RE +.PP +linknvme:nvme\-compare +.RS 4 +IO Compare +.RE +.PP +linknvme:nvme\-error\-log +.RS 4 +Retrieve error logs +.RE +.PP +linknvme:nvme\-flush +.RS 4 +Submit flush +.RE +.PP +linknvme:nvme\-format +.RS 4 +Format namespace(s) +.RE +.PP +linknvme:nvme\-fw\-activate +.RS 4 +F/W Activate +.RE +.PP +linknvme:nvme\-fw\-download +.RS 4 +F/W Download +.RE +.PP +linknvme:nvme\-fw\-log +.RS 4 +Retrieve f/w log +.RE +.PP +linknvme:nvme\-get\-feature +.RS 4 +Get Features +.RE +.PP +linknvme:nvme\-get\-log +.RS 4 +Generic Get Log +.RE +.PP +linknvme:nvme\-smart\-log +.RS 4 +Retrieve Smart Log +.RE +.PP +linknvme:nvme\-get\-ns\-id +.RS 4 +Retrieve namespace identifier +.RE +.PP +linknvme:nvme\-help +.RS 4 +NVMe CLI Help +.RE +.PP +linknvme:nvme\-id\-ctrl +.RS 4 +Identify Controller +.RE +.PP +linknvme:nvme\-id\-ns +.RS 4 +Identify Namespace +.RE +.PP +linknvme:nvme\-io\-passthru +.RS 4 +IO Passthrough Command +.RE +.PP +linknvme:nvme\-list\-ns +.RS 4 +List all nvme namespaces +.RE +.PP +linknvme:nvme\-list +.RS 4 +List all nvme controllers +.RE +.PP +linknvme:nvme\-read +.RS 4 +Issue IO Read Command +.RE +.PP +linknvme:nvme\-write +.RS 4 +Issue IO Write Command +.RE +.PP +linknvme:nvme\-resv\-acquire +.RS 4 +Acquire Namespace Reservation +.RE +.PP +linknvme:nvme\-resv\-register +.RS 4 +Register Namespace Reservation +.RE +.PP +linknvme:nvme\-resv\-release +.RS 4 +Release Namespace Reservation +.RE +.PP +linknvme:nvme\-resv\-report +.RS 4 +Report Reservation Capabilities +.RE +.PP +linknvme:nvme\-security\-recv +.RS 4 +Security Receive +.RE +.PP +linknvme:nvme\-security\-send +.RS 4 +Security Send +.RE +.PP +linknvme:nvme\-set\-feature +.RS 4 +Set Feature +.RE +.PP +linknvme:nvme\-show\-regs +.RS 4 +Show NVMe Controller Registers +.RE .SH "FURTHER DOCUMENTATION" .sp See the freely available references on the \m[blue]\fBOffical NVM\-Express Site\fR\m[]\&\s-2\u[1]\d\s+2\&. diff --git a/Documentation/nvme.html b/Documentation/nvme.html new file mode 100644 index 00000000..e5423cf2 --- /dev/null +++ b/Documentation/nvme.html @@ -0,0 +1,1047 @@ + + + + + +nvme(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme <command> <device> [<args>]
+
+
+
+
+
+

DESCRIPTION

+
+

NVM-Express is a fast, scalabale host controller interface designed to +address the needs for PCI Express based solida state drives.

+

This nvme program is a user space utility to provide standards compliant +tooling for NVM-Express drives. It was made specifically for Linux as +it relies on the IOCTLs defined by the mailine kernel driver.

+
+
+
+

NVME COMMANDS

+
+

The utility has sub-commands for all admin and io commands defined in the +specification and for displaying controller registers. There is also an +option to submit completely arbitrary commands. For a list of commands +available, run "nvme help".

+
+
+
+

nvme cli sub-commands

+
+
+

Main commands

+
+
+nvme-admin-passthru(1) +
+
+

+ Admin Passthrough Comand +

+
+
+nvme-compare(1) +
+
+

+ IO Compare +

+
+
+nvme-error-log(1) +
+
+

+ Retrieve error logs +

+
+
+nvme-flush(1) +
+
+

+ Submit flush +

+
+
+nvme-format(1) +
+
+

+ Format namespace(s) +

+
+
+nvme-fw-activate(1) +
+
+

+ F/W Activate +

+
+
+nvme-fw-download(1) +
+
+

+ F/W Download +

+
+
+nvme-fw-log(1) +
+
+

+ Retrieve f/w log +

+
+
+nvme-get-feature(1) +
+
+

+ Get Features +

+
+
+nvme-get-log(1) +
+
+

+ Generic Get Log +

+
+
+nvme-smart-log(1) +
+
+

+ Retrieve Smart Log +

+
+
+nvme-get-ns-id(1) +
+
+

+ Retrieve namespace identifier +

+
+
+nvme-help(1) +
+
+

+ NVMe CLI Help +

+
+
+nvme-id-ctrl(1) +
+
+

+ Identify Controller +

+
+
+nvme-id-ns(1) +
+
+

+ Identify Namespace +

+
+
+nvme-io-passthru(1) +
+
+

+ IO Passthrough Command +

+
+
+nvme-list-ns(1) +
+
+

+ List all nvme namespaces +

+
+
+nvme-list(1) +
+
+

+ List all nvme controllers +

+
+
+nvme-read(1) +
+
+

+ Issue IO Read Command +

+
+
+nvme-write(1) +
+
+

+ Issue IO Write Command +

+
+
+nvme-resv-acquire(1) +
+
+

+ Acquire Namespace Reservation +

+
+
+nvme-resv-register(1) +
+
+

+ Register Namespace Reservation +

+
+
+nvme-resv-release(1) +
+
+

+ Release Namespace Reservation +

+
+
+nvme-resv-report(1) +
+
+

+ Report Reservation Capabilities +

+
+
+nvme-security-recv(1) +
+
+

+ Security Receive +

+
+
+nvme-security-send(1) +
+
+

+ Security Send +

+
+
+nvme-set-feature(1) +
+
+

+ Set Feature +

+
+
+nvme-show-regs(1) +
+
+

+ Show NVMe Controller Registers +

+
+
+
+
+
+
+

FURTHER DOCUMENTATION

+
+

See the freely available references on the Offical +NVM-Express Site.

+
+
+
+

Authors

+
+

This is written and maintained by Keith Busch.

+
+
+
+

Reporting Bugs

+
+

Patches and issues may be submitted to the official repository at +https://github.com/linux-nvme/nvme-cli.

+
+
+
+

NVME

+
+

Part of the nvme suite

+
+
+
+
+ + + diff --git a/Documentation/nvme.txt b/Documentation/nvme.txt index 824062c1..31c695cf 100644 --- a/Documentation/nvme.txt +++ b/Documentation/nvme.txt @@ -26,6 +26,14 @@ specification and for displaying controller registers. There is also an option to submit completely arbitrary commands. For a list of commands available, run "nvme help". +nvme cli sub-commands +--------------------- + +Main commands +~~~~~~~~~~~~~ + +include::cmds-main.txt[] + FURTHER DOCUMENTATION --------------------- See the freely available references on the http://nvmexpress.org[Offical -- 2.50.1