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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
'\" t
.\" Title: nvme-admin-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\-ADMIN\-PASSTHR" "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-admin-passthru \- Submit an arbitrary admin command, return results
.SH "SYNOPSIS"
.sp
.nf
\fInvme\-admin\-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>]
[\-\-input\-file=<file> | \-i <file>]
[\-\-read | \-r] [\-\-write | \-w]
[\-\-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 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\&.
.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\&.
.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\&.
.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 a structure\&.
.RE
.PP
\-p, \-\-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 for 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
.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 corresponds 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
# nvme admin\-passthru /dev/nvme0 \-\-opcode=06 \-\-data\-len=4096 \-\-cdw10=1 \-r
.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
# nvme admin\-passthru /dev/nvme0 \-\-opcode=06 \-\-data\-len=4096 \-\-cdw10=1 \-r \-b > id_ns\&.raw
.fi
.if n \{\
.RE
.\}
.RE
.SH "NVME"
.sp
Part of the nvme\-user suite
|
