sbin/nvmecontrol/nvmecontrol.8

   1 .\"
   2 .\" Copyright (c) 2018-2019 Alexander Motin <mav@FreeBSD.org>
   3 .\" Copyright (c) 2012 Intel Corporation
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions, and the following disclaimer,
  11 .\"    without modification.
  12 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  13 .\"    substantially similar to the "NO WARRANTY" disclaimer below
  14 .\"    ("Disclaimer") and any redistribution must be conditioned upon
  15 .\"    including a substantially similar Disclaimer requirement for further
  16 .\"    binary redistribution.
  17 .\"
  18 .\" NO WARRANTY
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  22 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  27 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  28 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  29 .\" POSSIBILITY OF SUCH DAMAGES.
  30 .\"
  31 .\" nvmecontrol man page.
  32 .\"
  33 .\" Author: Jim Harris <jimharris@FreeBSD.org>
  34 .\"
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd August 1, 2019
  38 .Dt NVMECONTROL 8
  39 .Os
  40 .Sh NAME
  41 .Nm nvmecontrol
  42 .Nd NVM Express control utility
  43 .Sh SYNOPSIS
  44 .Nm
  45 .Ic devlist
  46 .Nm
  47 .Ic identify
  48 .Op Fl v
  49 .Op Fl x
  50 .Aq device id
  51 .Aq namespace id
  52 .Nm
  53 .Ic perftest
  54 .Aq Fl n Ar num_threads
  55 .Aq Fl o Ar read|write
  56 .Op Fl p
  57 .Aq Fl s Ar size_in_bytes
  58 .Aq Fl t Ar time_in_sec
  59 .Aq namespace id
  60 .Nm
  61 .Ic reset
  62 .Aq controller id
  63 .Nm
  64 .Ic logpage
  65 .Aq Fl p Ar page_id
  66 .Op Fl x
  67 .Op Fl v Ar vendor-string
  68 .Op Fl b
  69 .Aq device id
  70 .Aq namespace id
  71 .Nm
  72 .Ic ns active
  73 .Aq device id
  74 .Nm
  75 .Ic ns allocated
  76 .Aq device id
  77 .Nm
  78 .Ic ns attach
  79 .Aq Fl n Ar nsid
  80 .Aq Fl c Ar cntid
  81 .Aq device id
  82 .Nm
  83 .Ic ns attached
  84 .Aq Fl n Ar nsid
  85 .Aq device id
  86 .Nm
  87 .Ic ns controllers
  88 .Aq device id
  89 .Nm
  90 .Ic ns create
  91 .Aq Fl s Ar nsze
  92 .Op Fl c Ar ncap
  93 .Op Fl f Ar lbaf
  94 .Op Fl m Ar mset
  95 .Op Fl n Ar nmic
  96 .Op Fl p Ar pi
  97 .Op Fl l Ar pil
  98 .Op Fl L Ar flbas
  99 .Op Fl d Ar dps
 100 .Aq device id
 101 .Nm
 102 .Ic ns delete
 103 .Aq Fl n Ar nsid
 104 .Aq device id
 105 .Nm
 106 .Ic ns detach
 107 .Aq Fl n Ar nsid
 108 .Aq Fl c Ar cntid
 109 .Aq device id
 110 .Nm
 111 .Ic ns identify
 112 .Op Fl v
 113 .Op Fl x
 114 .Aq Fl n Ar nsid
 115 .Aq device id
 116 .Nm
 117 .Ic nsid
 118 .Aq device id
 119 .Aq namespace id
 120 .Nm
 121 .Ic firmware
 122 .Op Fl s Ar slot
 123 .Op Fl f Ar path_to_firmware
 124 .Op Fl a
 125 .Aq device id
 126 .Nm
 127 .Ic format
 128 .Op Fl f Ar fmt
 129 .Op Fl m Ar mset
 130 .Op Fl o Ar pi
 131 .Op Fl l Ar pil
 132 .Op Fl E
 133 .Op Fl C
 134 .Aq device id
 135 .Aq namespace id
 136 .Nm
 137 .Ic power
 138 .Op Fl l
 139 .Op Fl p power_state
 140 .Op Fl w workload_hint
 141 .Nm
 142 .Ic wdc cap-diag
 143 .Op Fl o path_template
 144 .Aq device id
 145 .Nm
 146 .Ic wdc drive-log
 147 .Op Fl o path_template
 148 .Aq device id
 149 .Nm
 150 .Ic wdc get-crash-dump
 151 .Op Fl o path_template
 152 .Aq device id
 153 .\" .Nm
 154 .\" .Ic wdc purge
 155 .\" .Aq device id
 156 .\" .Nm
 157 .\" .Ic wdc purge-monitor
 158 .\" .Aq device id
 159 .Sh DESCRIPTION
 160 NVM Express (NVMe) is a storage protocol standard, for SSDs and other
 161 high-speed storage devices over PCI Express.
 162 .Pp
 163 .Ss logpage
 164 The logpage command knows how to print log pages of various types.
 165 It also knows about vendor specific log pages from hgst/wdc and intel.
 166 Note that some vendors use the same log page numbers for different data.
 167 .Pp
 168 .Bl -tag -compact -width "Page 0x00"
 169 .It Dv Page 0x01
 170 Drive Error Log
 171 .It Dv Page 0x02
 172 Health/SMART Data
 173 .It Dv Page 0x03
 174 Firmware Information
 175 .It Dv Page 0xc1
 176 Advanced SMART information (WDC/HGST)
 177 .It Dv Page 0xc1
 178 Read latency stats (Intel)
 179 .It Dv Page 0xc2
 180 Wite latency stats (Intel)
 181 .It Dv Page 0xc5
 182 Temperature stats (Intel)
 183 .It Dv Page 0xca
 184 Advanced SMART information (Intel)
 185 .El
 186 .Pp
 187 Specifying
 188 .Fl p
 189 .Ic help
 190 will list all valid vendors and pages.
 191 .Fl x
 192 will print the page as hex.
 193 .Fl b
 194 will print the binary data for the page.
 195 .Ss ns
 196 Various namespace management commands.
 197 If namespace management is supported by device, allow list, create and delete
 198 namespaces, list, attach and detach controllers to namespaces.
 199 .Ss format
 200 Format either specified namespace, or all namespaces of specified controller,
 201 using specified parameters:
 202 .Ar fmt
 203 LBA Format,
 204 .Ar mset
 205 Metadata Settings,
 206 .Ar pi
 207 Protection Information,
 208 .Ar pil
 209 Protection Information Location.
 210 When formatting specific namespace, existing values are used as defaults.
 211 When formatting all namespaces, all parameters should be specified.
 212 Some controllers may not support formatting or erasing specific or all
 213 namespaces.
 214 Option
 215 .Fl E
 216 enables User Data Erase during format.
 217 Option
 218 .Fl C
 219 enables Cryptographic Erase during format.
 220 .Ss wdc
 221 The various wdc command retrieve log data from the wdc/hgst drives.
 222 The
 223 .Fl o
 224 flag specifies a path template to use to output the files.
 225 Each file takes the path template (which defaults to nothing), appends
 226 the drive's serial number and the type of dump it is followed
 227 by .bin.
 228 These logs must be sent to the vendor for analysis.
 229 This tool only provides a way to extract them.
 230 .Sh EXAMPLES
 231 .Dl nvmecontrol devlist
 232 .Pp
 233 Display a list of NVMe controllers and namespaces along with their device nodes.
 234 .Pp
 235 .Dl nvmecontrol identify nvme0
 236 .Pp
 237 Display a human-readable summary of the nvme0 IDENTIFY_CONTROLLER data.
 238 .Pp
 239 .Dl nvmecontrol identify -x -v nvme0ns1
 240 .Pp
 241 Display an hexadecimal dump of the nvme0 IDENTIFY_NAMESPACE data for namespace
 242 1.
 243 .Pp
 244 .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1
 245 .Pp
 246 Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds.
 247 Each thread will issue a single 512 byte read command.
 248 Results are printed to stdout when 30 seconds expires.
 249 .Pp
 250 .Dl nvmecontrol reset nvme0
 251 .Pp
 252 Perform a controller-level reset of the nvme0 controller.
 253 .Pp
 254 .Dl nvmecontrol logpage -p 1 nvme0
 255 .Pp
 256 Display a human-readable summary of the nvme0 controller's Error Information Log.
 257 Log pages defined by the NVMe specification include Error Information Log (ID=1),
 258 SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3).
 259 .Pp
 260 .Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0
 261 .Pp
 262 Display a human-readable summary of the nvme0's wdc-specific advanced
 263 SMART data.
 264 .Pp
 265 .Dl nvmecontrol logpage -p 1 -x nvme0
 266 .Pp
 267 Display a hexadecimal dump of the nvme0 controller's Error Information Log.
 268 .Pp
 269 .Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin
 270 .Pp
 271 Print the contents of vendor specific page 0xcb as binary data on
 272 standard out.
 273 Redirect it to a temporary file.
 274 .Pp
 275 .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0
 276 .Pp
 277 Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the
 278 nvme0 controller, but do not activate the image.
 279 .Pp
 280 .Dl nvmecontrol firmware -s 4 -a nvme0
 281 .Pp
 282 Activate the firmware in slot 4 of the nvme0 controller on the next reset.
 283 .Pp
 284 .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0
 285 .Pp
 286 Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the
 287 nvme0 controller and activate it on the next reset.
 288 .Pp
 289 .Dl nvmecontrol power -l nvme0
 290 .Pp
 291 List all the current power modes.
 292 .Pp
 293 .Dl nvmecontrol power -p 3 nvme0
 294 .Pp
 295 Set the current power mode.
 296 .Pp
 297 .Dl nvmecontrol power nvme0
 298 .Pp
 299 Get the current power mode.
 300 .Sh DYNAMIC LOADING
 301 The directories
 302 .Pa /lib/nvmecontrol
 303 and
 304 .Pa /usr/local/lib/nvmecontrol
 305 are scanned for any .so files.
 306 These files are loaded.
 307 The members of the
 308 .Va top
 309 linker set are added to the top-level commands.
 310 The members of the
 311 .Va logpage
 312 linker set are added to the logpage parsers.
 313 .Sh HISTORY
 314 The
 315 .Nm
 316 utility appeared in
 317 .Fx 9.2 .
 318 .Sh AUTHORS
 319 .An -nosplit
 320 .Nm
 321 was developed by Intel and originally written by
 322 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
 323 .Pp
 324 This man page was written by
 325 .An Jim Harris Aq Mt jimharris@FreeBSD.org .