summaryrefslogtreecommitdiffstats
path: root/Documentation/nvme-admin-passthru.txt
blob: c930e8c76bebedaa356a60010d28928f055b3bd8 (plain)
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
nvme-admin-passthru(1)
======================

NAME
----
nvme-admin-passthru - Submit an arbitrary admin command, return results

SYNOPSIS
--------
[verse]
'nvme-admin-passthru' <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]

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.

-[2-9] <cdw>::
--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. If want to use --dry-run option,
	--show-cmd option _must_ be set. Otherwise --dry-run option will be
	_ignored_.

-b::
--raw-binary::
	Print the raw returned buffer to stdout if the command returns
	a structure.

-p::
--prefill::
	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.

-T::
--latency::
	Print out the latency the IOCTL took (in us).

-o <fmt>::
--output-format=<fmt>::
	Set the reporting format to 'normal', 'json' or 'binary'. Only one
	output format can be used at a time.

-v::
--verbose::
	Increase the information detail in the output.

-t <timeout>::
--timeout=<timeout>::
	Override default timeout value. In milliseconds.

EXAMPLES
--------
* 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
+
------------
# 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