1NVME-IO-PASSTHRU(1)               NVMe Manual              NVME-IO-PASSTHRU(1)
2
3
4

NAME

6       nvme-io-passthru - Submit an arbitrary io command, return results
7

SYNOPSIS

9       nvme-io-passthru <device> [--opcode=<opcode> | -o <opcode>]
10                       [--flags=<flags> | -f <flags>] [-rsvd=<rsvd> | -R <rsvd>]
11                       [--namespace-id=<nsid> | -nsid <nsid>]
12                       [--cdw2=<cdw2>] [--cdw3=<cdw3>] [--cdw10=<cdw10>]
13                       [--cdw11=<cdw11>] [--cdw12=<cdw12>] [--cdw13=<cdw13>]
14                       [--cdw14=<cdw14>] [--cdw15=<cdw15>]
15                       [--data-len=<data-len> | -l <data-len>]
16                       [--metadata-len=<len> | -m <len>]
17                       [--read | -r ] [--write | -w]
18                       [--input-file=<file> | -i <file>]
19                       [--metadata=<file> | -M <file>]
20                       [--timeout=<to> | -t <to>]
21                       [--show-command | -s]
22                       [--dry-run | -d]
23                       [--raw-binary | -b]
24                       [--prefill=<prefill> | -p <prefill>]
25                       [--latency | -T]
26

DESCRIPTION

28       Submits an arbitrary NVMe IO command and returns the applicable
29       results. This may be the simply the command’s result and status, or may
30       also include a buffer if the command returns one. This command does no
31       interpretation of the opcodes or options.
32
33       The <device> parameter is mandatory and may be either the NVMe
34       character device (ex: /dev/nvme0), or a namespace block device (ex:
35       /dev/nvme0n1).
36
37       On success, the returned structure (if applicable) may be returned in
38       one of several ways depending on the option flags; the structure may
39       printed by the program as a hex dump, or may be returned as a raw
40       buffer printed to stdout for another program to parse.
41

OPTIONS

43       -o <opcode>, --opcode=<opcode>
44           The NVMe opcode to send to the device in the command
45
46       -f <flags>, --flags=<flags>
47           The NVMe command flags to send to the device in the command
48
49       -R <rsvd>, --rsvd=<rsvd>
50           The value for the reserved field in the command.
51
52       -n <nsid>, --namespace-id=<nsid>
53           The value for the ns-id in the command. Defaults to 0.
54
55       --cdw[2-3,10-15]=<cdw>
56           Specifies the command dword value for that specified entry in the
57           command
58
59       -r, --read, -w, --write
60           Used for the data-direction for the command and required for
61           commands sending/receiving data. Don’t use both read and write at
62           the same time.
63
64       -i <file>, --input-file=<file>
65           If the command is a data-out (write) command, use this file to fill
66           the buffer sent to the device. If no file is given, assumed to use
67           STDIN. If the command is a data-in (read) command, the data
68           returned from the device will be saved here.
69
70       -M <file>, --metadata=<file>
71           If the command is a data-out (write) command, use this file to fill
72           the metadata buffer sent to the device. If no file is given,
73           assumed to use STDIN. If the command is a data-in (read) command,
74           the metadata returned from the device will be saved here.
75
76       -l <data-len>, --data-len=<data-len>
77           The data length for the buffer used for this command.
78
79       -m <data-len>, --metadata-len=<data-len>
80           The metadata length for the buffer used for this command.
81
82       -s, --show-cmd
83           Print out the command to be sent.
84
85       -d, --dry-run
86           Do not actually send the command. If want to use --dry-run option,
87           --show-cmd option must be set. Otherwise --dry-run option will be
88           ignored.
89
90       -b, --raw-binary
91           Print the raw returned buffer to stdout if the command returns data
92           or a structure.
93
94       -p <prefill>, --prefill <prefill>
95           Prefill the buffer with a predetermined byte value. Defaults to 0.
96           This may be useful if the data you are writing is shorter than the
97           required buffer, and you need to pad it with a known value. It may
98           also be useful if you need to confirm if a device is overwriting a
99           buffer on a data-in command.
100
101       -T, --latency
102           Print out the latency the IOCTL took (in us).
103

EXAMPLES

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

NVME

109       Part of the nvme-user suite
110
111
112
113NVMe                              09/29/2023               NVME-IO-PASSTHRU(1)
Impressum