1NVME-ADMIN-PASSTHR(1)             NVMe Manual            NVME-ADMIN-PASSTHR(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

EXAMPLES

96       •   The following will run the admin command with opcode=6 and cdw10=1,
97           which corresponds to an identify controller command. This example
98           requires the data-len param be 4096, which is the size of the
99           returned structure. The -r option is used because it is a data-in
100           command
101
102               # nvme admin-passthru /dev/nvme0 --opcode=06 --data-len=4096 --cdw10=1 -r
103
104       •   Or if you want to save that structure to a file:
105
106               # nvme admin-passthru /dev/nvme0 --opcode=06 --data-len=4096 --cdw10=1 -r -b > id_ns.raw
107

NVME

109       Part of the nvme-user suite
110
111
112
113NVMe                              10/06/2023             NVME-ADMIN-PASSTHR(1)
Impressum