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 2, 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 .Op Fl f Ar LSP
  70 .Op Fl i Ar LSI
  71 .Op Fl r
  72 .Aq device id
  73 .Aq namespace id
  74 .Nm
  75 .Ic ns active
  76 .Aq device id
  77 .Nm
  78 .Ic ns allocated
  79 .Aq device id
  80 .Nm
  81 .Ic ns attach
  82 .Aq Fl n Ar nsid
  83 .Aq Fl c Ar cntid
  84 .Aq device id
  85 .Nm
  86 .Ic ns attached
  87 .Aq Fl n Ar nsid
  88 .Aq device id
  89 .Nm
  90 .Ic ns controllers
  91 .Aq device id
  92 .Nm
  93 .Ic ns create
  94 .Aq Fl s Ar nsze
  95 .Op Fl c Ar ncap
  96 .Op Fl f Ar lbaf
  97 .Op Fl m Ar mset
  98 .Op Fl n Ar nmic
  99 .Op Fl p Ar pi
 100 .Op Fl l Ar pil
 101 .Op Fl L Ar flbas
 102 .Op Fl d Ar dps
 103 .Aq device id
 104 .Nm
 105 .Ic ns delete
 106 .Aq Fl n Ar nsid
 107 .Aq device id
 108 .Nm
 109 .Ic ns detach
 110 .Aq Fl n Ar nsid
 111 .Aq Fl c Ar cntid
 112 .Aq device id
 113 .Nm
 114 .Ic ns identify
 115 .Op Fl v
 116 .Op Fl x
 117 .Aq Fl n Ar nsid
 118 .Aq device id
 119 .Nm
 120 .Ic nsid
 121 .Aq device id
 122 .Aq namespace id
 123 .Nm
 124 .Ic firmware
 125 .Op Fl s Ar slot
 126 .Op Fl f Ar path_to_firmware
 127 .Op Fl a
 128 .Aq device id
 129 .Nm
 130 .Ic format
 131 .Op Fl f Ar fmt
 132 .Op Fl m Ar mset
 133 .Op Fl o Ar pi
 134 .Op Fl l Ar pil
 135 .Op Fl E
 136 .Op Fl C
 137 .Aq device id
 138 .Aq namespace id
 139 .Nm
 140 .Ic power
 141 .Op Fl l
 142 .Op Fl p power_state
 143 .Op Fl w workload_hint
 144 .Nm
 145 .Ic wdc cap-diag
 146 .Op Fl o path_template
 147 .Aq device id
 148 .Nm
 149 .Ic wdc drive-log
 150 .Op Fl o path_template
 151 .Aq device id
 152 .Nm
 153 .Ic wdc get-crash-dump
 154 .Op Fl o path_template
 155 .Aq device id
 156 .\" .Nm
 157 .\" .Ic wdc purge
 158 .\" .Aq device id
 159 .\" .Nm
 160 .\" .Ic wdc purge-monitor
 161 .\" .Aq device id
 162 .Sh DESCRIPTION
 163 NVM Express (NVMe) is a storage protocol standard, for SSDs and other
 164 high-speed storage devices over PCI Express.
 165 .Pp
 166 .Ss logpage
 167 The logpage command knows how to print log pages of various types.
 168 It also knows about vendor specific log pages from hgst/wdc and intel.
 169 Note that some vendors use the same log page numbers for different data.
 170 .Pp
 171 .Bl -tag -compact -width "Page 0x00"
 172 .It Dv Page 0x01
 173 Drive Error Log
 174 .It Dv Page 0x02
 175 Health/SMART Data
 176 .It Dv Page 0x03
 177 Firmware Information
 178 .It Dv Page 0x04
 179 Changed Namespace List
 180 .It Dv Page 0x05
 181 Commands Supported and Effects
 182 .It Dv Page 0x80
 183 Reservation Notification
 184 .It Dv Page 0x81
 185 Sanitize Status
 186 .It Dv Page 0xc1
 187 Advanced SMART information (WDC/HGST)
 188 .It Dv Page 0xc1
 189 Read latency stats (Intel)
 190 .It Dv Page 0xc2
 191 Wite latency stats (Intel)
 192 .It Dv Page 0xc5
 193 Temperature stats (Intel)
 194 .It Dv Page 0xca
 195 Advanced SMART information (Intel)
 196 .El
 197 .Pp
 198 Specifying
 199 .Fl v
 200 .Ic help
 201 will list all valid vendors and pages.
 202 .Fl x
 203 will print the page as hex.
 204 .Fl b
 205 will print the binary data for the page.
 206 .Fl s
 207 will set Log Specific Field.
 208 .Fl i
 209 will set Log Specific Identifier.
 210 .Fl r
 211 will set Retain Asynchronous Event.
 212 .Ss ns
 213 Various namespace management commands.
 214 If namespace management is supported by device, allow list, create and delete
 215 namespaces, list, attach and detach controllers to namespaces.
 216 .Ss format
 217 Format either specified namespace, or all namespaces of specified controller,
 218 using specified parameters:
 219 .Ar fmt
 220 LBA Format,
 221 .Ar mset
 222 Metadata Settings,
 223 .Ar pi
 224 Protection Information,
 225 .Ar pil
 226 Protection Information Location.
 227 When formatting specific namespace, existing values are used as defaults.
 228 When formatting all namespaces, all parameters should be specified.
 229 Some controllers may not support formatting or erasing specific or all
 230 namespaces.
 231 Option
 232 .Fl E
 233 enables User Data Erase during format.
 234 Option
 235 .Fl C
 236 enables Cryptographic Erase during format.
 237 .Ss wdc
 238 The various wdc command retrieve log data from the wdc/hgst drives.
 239 The
 240 .Fl o
 241 flag specifies a path template to use to output the files.
 242 Each file takes the path template (which defaults to nothing), appends
 243 the drive's serial number and the type of dump it is followed
 244 by .bin.
 245 These logs must be sent to the vendor for analysis.
 246 This tool only provides a way to extract them.
 247 .Sh EXAMPLES
 248 .Dl nvmecontrol devlist
 249 .Pp
 250 Display a list of NVMe controllers and namespaces along with their device nodes.
 251 .Pp
 252 .Dl nvmecontrol identify nvme0
 253 .Pp
 254 Display a human-readable summary of the nvme0 IDENTIFY_CONTROLLER data.
 255 .Pp
 256 .Dl nvmecontrol identify -x -v nvme0ns1
 257 .Pp
 258 Display an hexadecimal dump of the nvme0 IDENTIFY_NAMESPACE data for namespace
 259 1.
 260 .Pp
 261 .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1
 262 .Pp
 263 Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds.
 264 Each thread will issue a single 512 byte read command.
 265 Results are printed to stdout when 30 seconds expires.
 266 .Pp
 267 .Dl nvmecontrol reset nvme0
 268 .Pp
 269 Perform a controller-level reset of the nvme0 controller.
 270 .Pp
 271 .Dl nvmecontrol logpage -p 1 nvme0
 272 .Pp
 273 Display a human-readable summary of the nvme0 controller's Error Information Log.
 274 Log pages defined by the NVMe specification include Error Information Log (ID=1),
 275 SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3).
 276 .Pp
 277 .Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0
 278 .Pp
 279 Display a human-readable summary of the nvme0's wdc-specific advanced
 280 SMART data.
 281 .Pp
 282 .Dl nvmecontrol logpage -p 1 -x nvme0
 283 .Pp
 284 Display a hexadecimal dump of the nvme0 controller's Error Information Log.
 285 .Pp
 286 .Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin
 287 .Pp
 288 Print the contents of vendor specific page 0xcb as binary data on
 289 standard out.
 290 Redirect it to a temporary file.
 291 .Pp
 292 .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0
 293 .Pp
 294 Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the
 295 nvme0 controller, but do not activate the image.
 296 .Pp
 297 .Dl nvmecontrol firmware -s 4 -a nvme0
 298 .Pp
 299 Activate the firmware in slot 4 of the nvme0 controller on the next reset.
 300 .Pp
 301 .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0
 302 .Pp
 303 Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the
 304 nvme0 controller and activate it on the next reset.
 305 .Pp
 306 .Dl nvmecontrol power -l nvme0
 307 .Pp
 308 List all the current power modes.
 309 .Pp
 310 .Dl nvmecontrol power -p 3 nvme0
 311 .Pp
 312 Set the current power mode.
 313 .Pp
 314 .Dl nvmecontrol power nvme0
 315 .Pp
 316 Get the current power mode.
 317 .Sh DYNAMIC LOADING
 318 The directories
 319 .Pa /lib/nvmecontrol
 320 and
 321 .Pa /usr/local/lib/nvmecontrol
 322 are scanned for any .so files.
 323 These files are loaded.
 324 The members of the
 325 .Va top
 326 linker set are added to the top-level commands.
 327 The members of the
 328 .Va logpage
 329 linker set are added to the logpage parsers.
 330 .Sh HISTORY
 331 The
 332 .Nm
 333 utility appeared in
 334 .Fx 9.2 .
 335 .Sh AUTHORS
 336 .An -nosplit
 337 .Nm
 338 was developed by Intel and originally written by
 339 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
 340 .Pp
 341 This man page was written by
 342 .An Jim Harris Aq Mt jimharris@FreeBSD.org .