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

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

SYNOPSIS
--------
[verse]
'nvme-io-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>]
			[--read | -r] [--write | -w]
			[--input-file=<file> | -i <file>]
			[--metadata=<file> | -M <file>]
			[--timeout=<to> | -t <to>] [--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 IO command and returns the applicable
results. This may be the simply the command's 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. Defaults to '0'.

-[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. If the command is a data-in (read) command, the data
	returned from the device will be saved here.

-M <file>::
--metadata=<file>::
	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.

-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
	data or a structure.

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

EXAMPLES
--------

nvme io-passthru /dev/nvme0n1 --opcode=2 --namespace-id=1 --data-len=4096 --read --cdw10=0 --cdw11=0 --cdw12=0x70000 --raw-binary

NVME
----
Part of the nvme-user suite