sbin/nvmecontrol/nvmecontrol.8

   1 .\"
   2 .\" Copyright (c) 2018 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 December 7, 2018
  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 firmware
  73 .Op Fl s Ar slot
  74 .Op Fl f Ar path_to_firmware
  75 .Op Fl a
  76 .Aq device id
  77 .Nm
  78 .Ic format
  79 .Op Fl f Ar fmt
  80 .Op Fl m Ar mset
  81 .Op Fl o Ar pi
  82 .Op Fl l Ar pil
  83 .Op Fl E
  84 .Op Fl C
  85 .Aq device id
  86 .Aq namespace id
  87 .Nm
  88 .Ic power
  89 .Op Fl l
  90 .Op Fl p power_state
  91 .Op Fl w workload_hint
  92 .Nm
  93 .Ic wdc cap-diag
  94 .Op Fl o path_template
  95 .Aq device id
  96 .Nm
  97 .Ic wdc drive-log
  98 .Op Fl o path_template
  99 .Aq device id
 100 .Nm
 101 .Ic wdc get-crash-dump
 102 .Op Fl o path_template
 103 .Aq device id
 104 .\" .Nm
 105 .\" .Ic wdc purge
 106 .\" .Aq device id
 107 .\" .Nm
 108 .\" .Ic wdc purge-monitor
 109 .\" .Aq device id
 110 .Sh DESCRIPTION
 111 NVM Express (NVMe) is a storage protocol standard, for SSDs and other
 112 high-speed storage devices over PCI Express.
 113 .Pp
 114 .Ss logpage
 115 The logpage command knows how to print log pages of various types.
 116 It also knows about vendor specific log pages from hgst/wdc and intel.
 117 Page 0xc1 for hgst/wdc contains the advanced smart information about
 118 the drive.
 119 Page 0xc1 is read latency stats for intel.
 120 Page 0xc2 is write latency stats for intel.
 121 Page 0xc5 is temperature stats for intel.
 122 Page 0xca is advanced smart information for intel.
 123 .Pp
 124 Specifying
 125 .Fl p
 126 .Ic help
 127 will list all valid vendors and pages.
 128 .Fl x
 129 will print the page as hex.
 130 .Fl b
 131 will print the binary data for the page.
 132 .Ss format
 133 Format either specified namespace, or all namespaces of specified controller,
 134 using specified parameters:
 135 .Ar fmt
 136 LBA Format,
 137 .Ar mset
 138 Metadata Settings,
 139 .Ar pi
 140 Protection Information,
 141 .Ar pil
 142 Protection Information Location.
 143 When formatting specific namespace, existing values are used as defaults.
 144 When formatting all namespaces, all parameters should be specified.
 145 Some controllers may not support formatting or erasing specific or all
 146 namespaces.
 147 Option
 148 .Fl E
 149 enables User Data Erase during format.
 150 Option
 151 .Fl C
 152 enables Cryptographic Erase during format.
 153 .Ss wdc
 154 The various wdc command retrieve log data from the wdc/hgst drives.
 155 The
 156 .Fl o
 157 flag specifies a path template to use to output the files.
 158 Each file takes the path template (which defaults to nothing), appends
 159 the drive's serial number and the type of dump it is followed
 160 by .bin.
 161 These logs must be sent to the vendor for analysis.
 162 This tool only provides a way to extract them.
 163 .Sh EXAMPLES
 164 .Dl nvmecontrol devlist
 165 .Pp
 166 Display a list of NVMe controllers and namespaces along with their device nodes.
 167 .Pp
 168 .Dl nvmecontrol identify nvme0
 169 .Pp
 170 Display a human-readable summary of the nvme0 IDENTIFY_CONTROLLER data.
 171 .Pp
 172 .Dl nvmecontrol identify -x -v nvme0ns1
 173 .Pp
 174 Display an hexadecimal dump of the nvme0 IDENTIFY_NAMESPACE data for namespace
 175 1.
 176 .Pp
 177 .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1
 178 .Pp
 179 Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds.
 180 Each thread will issue a single 512 byte read command.
 181 Results are printed to stdout when 30 seconds expires.
 182 .Pp
 183 .Dl nvmecontrol reset nvme0
 184 .Pp
 185 Perform a controller-level reset of the nvme0 controller.
 186 .Pp
 187 .Dl nvmecontrol logpage -p 1 nvme0
 188 .Pp
 189 Display a human-readable summary of the nvme0 controller's Error Information Log.
 190 Log pages defined by the NVMe specification include Error Information Log (ID=1),
 191 SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3).
 192 .Pp
 193 .Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0
 194 .Pp
 195 Display a human-readable summary of the nvme0's wdc-specific advanced
 196 SMART data.
 197 .Pp
 198 .Dl nvmecontrol logpage -p 1 -x nvme0
 199 .Pp
 200 Display a hexadecimal dump of the nvme0 controller's Error Information Log.
 201 .Pp
 202 .Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin
 203 .Pp
 204 Print the contents of vendor specific page 0xcb as binary data on
 205 standard out.
 206 Redirect it to a temporary file.
 207 .Pp
 208 .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0
 209 .Pp
 210 Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the
 211 nvme0 controller, but do not activate the image.
 212 .Pp
 213 .Dl nvmecontrol firmware -s 4 -a nvme0
 214 .Pp
 215 Activate the firmware in slot 4 of the nvme0 controller on the next reset.
 216 .Pp
 217 .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0
 218 .Pp
 219 Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the
 220 nvme0 controller and activate it on the next reset.
 221 .Pp
 222 .Dl nvmecontrol power -l nvme0
 223 .Pp
 224 List all the current power modes.
 225 .Pp
 226 .Dl nvmecontrol power -p 3 nvme0
 227 .Pp
 228 Set the current power mode.
 229 .Pp
 230 .Dl nvmecontrol power nvme0
 231 .Pp
 232 Get the current power mode.
 233 .Sh DYNAMIC LOADING
 234 The directories
 235 .Pa /lib/nvmecontrol
 236 and
 237 .Pa /usr/local/lib/nvmecontrol
 238 are scanned for any .so files.
 239 These files are loaded.
 240 The members of the
 241 .Va top
 242 linker set are added to the top-level commands.
 243 The members of the
 244 .Va logpage
 245 linker set are added to the logpage parsers.
 246 .Sh HISTORY
 247 The
 248 .Nm
 249 utility appeared in
 250 .Fx 9.2 .
 251 .Sh AUTHORS
 252 .An -nosplit
 253 .Nm
 254 was developed by Intel and originally written by
 255 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
 256 .Pp
 257 This man page was written by
 258 .An Jim Harris Aq Mt jimharris@FreeBSD.org .