diff options
Diffstat (limited to 'Documentation/nvme-read.1')
| -rw-r--r-- | Documentation/nvme-read.1 | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/Documentation/nvme-read.1 b/Documentation/nvme-read.1 new file mode 100644 index 0000000..ae7faf6 --- /dev/null +++ b/Documentation/nvme-read.1 @@ -0,0 +1,186 @@ +'\" t +.\" Title: nvme-read +.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 04/24/2020 +.\" Manual: NVMe Manual +.\" Source: NVMe +.\" Language: English +.\" +.TH "NVME\-READ" "1" "04/24/2020" "NVMe" "NVMe Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +nvme-read \- Send an NVMe Read command, provide results +.SH "SYNOPSIS" +.sp +.nf +\fInvme\-read\fR <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>] + [\-\-metadata=<metadata\-file> | \-M <metadata\-file>] + [\-\-prinfo=<prinfo> | \-p <prinfo>] + [\-\-app\-tag\-mask=<appmask> | \-m <appmask>] + [\-\-app\-tag=<apptag> | \-a <apptag>] + [\-\-limited\-retry | \-l] + [\-\-force\-unit\-access | \-f] + [\-\-dir\-type=<type> | \-T <type>] + [\-\-dir\-spec=<spec> | \-S <spec>] + [\-\-dsm=<dsm> | \-D <dsm>] + [\-\-show\-command | \-v] + [\-\-dry\-run | \-w] + [\-\-latency | \-t] +.fi +.SH "DESCRIPTION" +.sp +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\(cqt provide a file\&. +.SH "OPTIONS" +.PP +\-\-start\-block=<slba>, \-s <slba> +.RS 4 +Start block\&. +.RE +.PP +\-\-block\-count, \-c +.RS 4 +The number of blocks to transfer\&. This is a zeroes based value to align with the kernel\(cqs use of this field\&. (ie\&. 0 means transfer 1 block)\&. +.RE +.PP +\-\-data\-size=<size>, \-z <size> +.RS 4 +Size of data, in bytes\&. +.RE +.PP +\-\-metadata\-size=<size>, \-y <size> +.RS 4 +Size of metadata in bytes\&. +.RE +.PP +\-\-data=<data\-file>, \-d <data\-file> +.RS 4 +Data file\&. If none provided, contents are sent to STDOUT\&. +.RE +.PP +\-\-metadata=<metadata\-file>, \-M <metadata\-file> +.RS 4 +Metadata file, if necessary\&. +.RE +.PP +\-\-prinfo=<prinfo>, \-p <prinfo> +.RS 4 +Protection Information field definition\&. +.TS +allbox tab(:); +lt lt +lt lt +lt lt +lt lt +lt lt +lt lt. +T{ +Bit +T}:T{ +Description +T} +T{ +3 +T}:T{ +PRACT: Protection Information Action\&. When set to 1, PI is stripped/inserted on read/write when the block format\(cqs metadata size is 8\&. When set to 0, metadata is passes\&. +T} +T{ +2:0 +T}:T{ +PRCHK: Protection Information Check: +T} +T{ +2 +T}:T{ +Set to 1 enables checking the guard tag +T} +T{ +1 +T}:T{ +Set to 1 enables checking the application tag +T} +T{ +0 +T}:T{ +Set to 1 enables checking the reference tag +T} +.TE +.sp 1 +.RE +.PP +\-\-ref\-tag=<reftag>, \-r <reftag> +.RS 4 +Optional reftag when used with protection information\&. +.RE +.PP +\-\-app\-tag\-mask=<appmask>, \-m <appmask> +.RS 4 +Optional application tag mask when used with protection information\&. +.RE +.PP +\-\-force\-unit\-access, \-f +.RS 4 +Set the force\-unit access flag\&. +.RE +.PP +\-T <type>, \-\-dir\-type=<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 <spec>, \-\-dir\-spec=<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>, \-\-dsm=<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 option will be +\fIignored\fR\&. +.RE +.PP +\-t, \-\-latency +.RS 4 +Print out the latency the IOCTL took (in us)\&. +.RE +.SH "EXAMPLES" +.sp +No examples yet\&. +.SH "NVME" +.sp +Part of the nvme\-user suite |