'\" t

.\"     Title: nvme-write

.\"    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\-WRITE" "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-write \- Send an NVMe write command, provide results

.SH "SYNOPSIS"

.sp

.nf

\fInvme\-write\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 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\(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 from STDIN\&.

.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

\-\-app\-tag=<apptag>, \-a <apptag>

.RS 4

Optional application tag when used with protection information\&.

.RE

.PP

\-\-limited\-retry, \-l

.RS 4

Sets the limited retry flag\&.

.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