1NVME-READ(1)                      NVMe Manual                     NVME-READ(1)
2
3
4

NAME

6       nvme-read - Send an NVMe Read command, provide results
7

SYNOPSIS

9       nvme-read <device> [--start-block=<slba> | -s <slba>]
10                               [--block-count=<nlb> | -c <nlb>]
11                               [--data-size=<size> | -z <size>]
12                               [--metadata-size=<size> | -y <size>]
13                               [--ref-tag=<reftag> | -r <reftag>]
14                               [--data=<data-file> | -d <data-file>]
15                               [--metadata=<metadata-file> | -M <metadata-file>]
16                               [--prinfo=<prinfo> | -p <prinfo>]
17                               [--app-tag-mask=<appmask> | -m <appmask>]
18                               [--app-tag=<apptag> | -a <apptag>]
19                               [--limited-retry | -l]
20                               [--force-unit-access | -f]
21                               [--dir-type=<type> | -T <type>]
22                               [--dir-spec=<spec> | -S <spec>]
23                               [--dsm=<dsm> | -D <dsm>]
24                               [--show-command | -v]
25                               [--dry-run | -w]
26                               [--latency | -t]
27                               [--storage-tag<storage-tag> | -g <storage-tag>]
28                               [--storage-tag-check | -C ]
29                               [--force]
30

DESCRIPTION

32       The Read command reads the logical blocks specified by the command from
33       the medium and copies to the data data buffer provided. Will use stdout
34       by default if you don’t provide a file.
35

OPTIONS

37       --start-block=<slba>, -s <slba>
38           Start block.
39
40       --block-count, -c
41           The number of blocks to transfer. This is a zeroes based value to
42           align with the kernel’s use of this field. (ie. 0 means transfer 1
43           block).
44
45       --data-size=<size>, -z <size>
46           Size of data, in bytes.
47
48       --metadata-size=<size>, -y <size>
49           Size of metadata in bytes.
50
51       --data=<data-file>, -d <data-file>
52           Data file. If none provided, contents are sent to STDOUT.
53
54       --metadata=<metadata-file>, -M <metadata-file>
55           Metadata file, if necessary.
56
57       --prinfo=<prinfo>, -p <prinfo>
58           Protection Information field definition.
59
60           ┌────┬────────────────────────────┐
61           │Bit │ Description                │
62           ├────┼────────────────────────────┤
63           │3   │ PRACT: Protection          │
64           │    │ Information Action. When   │
65           │    │ set to 1, PI is            │
66           │    │ stripped/inserted on       │
67           │    │ read/write when the block  │
68           │    │ format’s metadata size is  │
69           │    │ 8. When set to 0, metadata │
70           │    │ is passes.                 │
71           ├────┼────────────────────────────┤
72           │2:0 │ PRCHK: Protection          │
73           │    │ Information Check:         │
74           ├────┼────────────────────────────┤
75           │2   │ Set to 1 enables checking  │
76           │    │ the guard tag              │
77           ├────┼────────────────────────────┤
78           │1   │ Set to 1 enables checking  │
79           │    │ the application tag        │
80           ├────┼────────────────────────────┤
81           │0   │ Set to 1 enables checking  │
82           │    │ the reference tag          │
83           └────┴────────────────────────────┘
84
85       --ref-tag=<reftag>, -r <reftag>
86           Optional reftag when used with protection information.
87
88       --app-tag-mask=<appmask>, -m <appmask>
89           Optional application tag mask when used with protection
90           information.
91
92       --force-unit-access, -f
93           Set the force-unit access flag.
94
95       -T <type>, --dir-type=<type>
96           Optional directive type. The nvme-cli only enforces the value be in
97           the defined range for the directive type, though the NVMe
98           specification (1.3a) defines only one directive, 01h, for write
99           stream identifiers.
100
101       -S <spec>, --dir-spec=<spec>
102           Optional field for directive specifics. When used with write
103           streams, this value is defined to be the write stream identifier.
104           The nvme-cli will not validate the stream requested is within the
105           controller’s capabilities.
106
107       -D <dsm>, --dsm=<dsm>
108           The optional data set management attributes for this command. The
109           argument for this is the least significant 8 bits of the DSM field
110           in a write command; the most significant 16 bits of the field come
111           from the directive specific field, if used. This may be used to set
112           attributes for the LBAs being written, like access frequency, type,
113           latency, among other things, as well as yet to be defined types.
114           Please consult the NVMe specification for detailed breakdown of how
115           to use this field.
116
117       -v, --show-cmd
118           Print out the command to be sent.
119
120       -w, --dry-run
121           Do not actually send the command. If want to use --dry-run option,
122           --show-cmd option must be set. Otherwise --dry-run option will be
123           ignored.
124
125       -t, --latency
126           Print out the latency the IOCTL took (in us).
127
128       -g <storage-tag>, --storage-tag=<storage-tag>
129           Variable Sized Expected Logical Block Storage Tag(ELBST).
130
131       -C, --storage-tag-check
132           This flag enables Storage Tag field checking as part of end-to-end
133           data protection processing.
134
135       --force
136           Ignore namespace is currently busy and performed the operation even
137           though.
138

EXAMPLES

140       No examples yet.
141

NVME

143       Part of the nvme-user suite
144
145
146
147NVMe                              10/06/2023                      NVME-READ(1)
Impressum