1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
'\" t
.\" Title: nvme-io-passthru
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 08/02/2024
.\" Manual: NVMe Manual
.\" Source: NVMe
.\" Language: English
.\"
.TH "NVME\-IO\-PASSTHRU" "1" "08/02/2024" "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-io-passthru \- Submit an arbitrary io command, return results
.SH "SYNOPSIS"
.sp
.nf
\fInvme\-io\-passthru\fR <device> [\-\-opcode=<opcode> | \-O <opcode>]
[\-\-flags=<flags> | \-f <flags>] [\-rsvd=<rsvd> | \-R <rsvd>]
[\-\-namespace\-id=<nsid> | \-n <nsid>] [\-\-cdw2=<cdw2> | \-2 <cdw2>]
[\-\-cdw3=<cdw3> | \-3 <cdw3>] [\-\-cdw10=<cdw10> | \-4 <cdw10>]
[\-\-cdw11=<cdw11> | \-5 <cdw11>] [\-\-cdw12=<cdw12> | \-6 <cdw12>]
[\-\-cdw13=<cdw13> | \-7 <cdw13>] [\-\-cdw14=<cdw14> | \-8 <cdw14>]
[\-\-cdw15=<cdw15> | \-9 <cdw15>]
[\-\-data\-len=<data\-len> | \-l <data\-len>]
[\-\-metadata\-len=<len> | \-m <len>]
[\-\-read | \-r] [\-\-write | \-w]
[\-\-input\-file=<file> | \-i <file>]
[\-\-metadata=<file> | \-M <file>]
[\-\-timeout=<timeout> | \-t <timeout>] [\-\-show\-command | \-s]
[\-\-dry\-run | \-d] [\-\-raw\-binary | \-b]
[\-\-prefill=<prefill> | \-p <prefill>]
[\-\-latency | \-T]
[\-\-output\-format=<fmt> | \-o <fmt>] [\-\-verbose | \-v]
.fi
.SH "DESCRIPTION"
.sp
Submits an arbitrary NVMe IO command and returns the applicable results\&. This may be the simply the command\(cqs result and status, or may also include a buffer if the command returns one\&. This command does no interpretation of the opcodes or options\&.
.sp
The <device> parameter is mandatory and may be either the NVMe character device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1)\&.
.sp
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\&.
.SH "OPTIONS"
.PP
\-O <opcode>, \-\-opcode=<opcode>
.RS 4
The NVMe opcode to send to the device in the command
.RE
.PP
\-f <flags>, \-\-flags=<flags>
.RS 4
The NVMe command flags to send to the device in the command
.RE
.PP
\-R <rsvd>, \-\-rsvd=<rsvd>
.RS 4
The value for the reserved field in the command\&.
.RE
.PP
\-n <nsid>, \-\-namespace\-id=<nsid>
.RS 4
The value for the ns\-id in the command\&. Defaults to
\fI0\fR\&.
.RE
.PP
\-[2\-9] <cdw>, \-\-cdw[2\-3,10\-15]=<cdw>
.RS 4
Specifies the command dword value for that specified entry in the command
.RE
.PP
\-r, \-\-read, \-w, \-\-write
.RS 4
Used for the data\-direction for the command and required for commands sending/receiving data\&. Don\(cqt use both read and write at the same time\&.
.RE
.PP
\-i <file>, \-\-input\-file=<file>
.RS 4
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\&. If the command is a data\-in (read) command, the data returned from the device will be saved here\&.
.RE
.PP
\-M <file>, \-\-metadata=<file>
.RS 4
If the command is a data\-out (write) command, use this file to fill the metadata buffer sent to the device\&. If no file is given, assumed to use STDIN\&. If the command is a data\-in (read) command, the metadata returned from the device will be saved here\&.
.RE
.PP
\-l <data\-len>, \-\-data\-len=<data\-len>
.RS 4
The data length for the buffer used for this command\&.
.RE
.PP
\-m <data\-len>, \-\-metadata\-len=<data\-len>
.RS 4
The metadata length for the buffer used for this command\&.
.RE
.PP
\-s, \-\-show\-cmd
.RS 4
Print out the command to be sent\&.
.RE
.PP
\-d, \-\-dry\-run
.RS 4
Do not actually send the command\&. If want to use \-\-dry\-run option, \-\-show\-cmd option
\fImust\fR
be set\&. Otherwise \-\-dry\-run option will be
\fIignored\fR\&.
.RE
.PP
\-b, \-\-raw\-binary
.RS 4
Print the raw returned buffer to stdout if the command returns data or a structure\&.
.RE
.PP
\-p <prefill>, \-\-prefill <prefill>
.RS 4
Prefill the buffer with a predetermined byte value\&. Defaults to 0\&. This may be useful if the data you are writing is shorter than the required buffer, and you need to pad it with a known value\&. It may also be useful if you need to confirm if a device is overwriting a buffer on a data\-in command\&.
.RE
.PP
\-T, \-\-latency
.RS 4
Print out the latency the IOCTL took (in us)\&.
.RE
.PP
\-o <fmt>, \-\-output\-format=<fmt>
.RS 4
Set the reporting format to
\fInormal\fR,
\fIjson\fR
or
\fIbinary\fR\&. Only one output format can be used at a time\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
Increase the information detail in the output\&.
.RE
.PP
\-t <timeout>, \-\-timeout=<timeout>
.RS 4
Override default timeout value\&. In milliseconds\&.
.RE
.SH "EXAMPLES"
.sp
nvme io\-passthru /dev/nvme0n1 \-\-opcode=2 \-\-namespace\-id=1 \-\-data\-len=4096 \-\-read \-\-cdw10=0 \-\-cdw11=0 \-\-cdw12=0x70000 \-\-raw\-binary
.SH "NVME"
.sp
Part of the nvme\-user suite
|
