sbin/nvmecontrol/nvmecontrol.8

   1 .\"
   2 .\" Copyright (c) 2012 Intel Corporation
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions, and the following disclaimer,
  10 .\"    without modification.
  11 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  12 .\"    substantially similar to the "NO WARRANTY" disclaimer below
  13 .\"    ("Disclaimer") and any redistribution must be conditioned upon
  14 .\"    including a substantially similar Disclaimer requirement for further
  15 .\"    binary redistribution.
  16 .\"
  17 .\" NO WARRANTY
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  21 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  26 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  27 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGES.
  29 .\"
  30 .\" nvmecontrol man page.
  31 .\"
  32 .\" Author: Jim Harris <jimharris@FreeBSD.org>
  33 .\"
  34 .\" $FreeBSD$
  35 .\"
  36 .Dd February 24, 2017
  37 .Dt NVMECONTROL 8
  38 .Os
  39 .Sh NAME
  40 .Nm nvmecontrol
  41 .Nd NVM Express control utility
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Ic devlist
  45 .Nm
  46 .Ic identify
  47 .Op Fl v
  48 .Op Fl x
  49 .Aq device id
  50 .Nm
  51 .Ic perftest
  52 .Aq Fl n Ar num_threads
  53 .Aq Fl o Ar read|write
  54 .Op Fl p
  55 .Aq Fl s Ar size_in_bytes
  56 .Aq Fl t Ar time_in_sec
  57 .Aq namespace id
  58 .Nm
  59 .Ic reset
  60 .Aq controller id
  61 .Nm
  62 .Ic logpage
  63 .Aq Fl p Ar page_id
  64 .Op Fl x
  65 .Op Fl v Ar vendor-string
  66 .Op Fl b
  67 .Aq device id
  68 .Aq namespace id
  69 .Nm
  70 .Ic firmware
  71 .Op Fl s Ar slot
  72 .Op Fl f Ar path_to_firmware
  73 .Op Fl a
  74 .Aq device id
  75 .Nm
  76 .Ic power
  77 .Op Fl l
  78 .Op Fl p power_state
  79 .Op Fl w workload_hint
  80 .Nm
  81 .Ic wdc cap-diag
  82 .Op Fl o path_template
  83 .Aq device id
  84 .Nm
  85 .Ic wdc drive-log
  86 .Op Fl o path_template
  87 .Aq device id
  88 .Nm
  89 .Ic wdc get-crash-dump
  90 .Op Fl o path_template
  91 .Aq device id
  92 .\" .Nm
  93 .\" .Ic wdc purge
  94 .\" .Aq device id
  95 .\" .Nm
  96 .\" .Ic wdc purge-monitor
  97 .\" .Aq device id
  98 .Sh DESCRIPTION
  99 NVM Express (NVMe) is a storage protocol standard, for SSDs and other
 100 high-speed storage devices over PCI Express.
 101 .Pp
 102 .Ss logpage
 103 The logpage command knows how to print log pages of various types.
 104 It also knows about vendor specific log pages from hgst/wdc and intel.
 105 Page 0xc1 for hgst/wdc contains the advanced smart information about
 106 the drive.
 107 Page 0xc1 is read latency stats for intel.
 108 Page 0xc2 is write latency stats for intel.
 109 Page 0xc5 is temperature stats for intel.
 110 Page 0xca is advanced smart information for intel.
 111 .Pp
 112 Specifying
 113 .Fl p
 114 .Ic help
 115 will list all valid vendors and pages.
 116 .Fl x
 117 will print the page as hex.
 118 .Fl b
 119 will print the binary data for the page.
 120 .Ss wdc
 121 The various wdc command retrieve log data from the wdc/hgst drives.
 122 The
 123 .Fl o
 124 flag specifies a path template to use to output the files.
 125 Each file takes the path template (which defaults to nothing), appends
 126 the drive's serial number and the type of dump it is followed
 127 by .bin.
 128 These logs must be sent to the vendor for analysis.
 129 This tool only provides a way to extract them.
 130 .Sh EXAMPLES
 131 .Dl nvmecontrol devlist
 132 .Pp
 133 Display a list of NVMe controllers and namespaces along with their device nodes.
 134 .Pp
 135 .Dl nvmecontrol identify nvme0
 136 .Pp
 137 Display a human-readable summary of the nvme0 IDENTIFY_CONTROLLER data.
 138 .Pp
 139 .Dl nvmecontrol identify -x -v nvme0ns1
 140 .Pp
 141 Display an hexadecimal dump of the nvme0 IDENTIFY_NAMESPACE data for namespace
 142 1.
 143 .Pp
 144 .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1
 145 .Pp
 146 Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds.
 147 Each thread will issue a single 512 byte read command.
 148 Results are printed to stdout when 30 seconds expires.
 149 .Pp
 150 .Dl nvmecontrol reset nvme0
 151 .Pp
 152 Perform a controller-level reset of the nvme0 controller.
 153 .Pp
 154 .Dl nvmecontrol logpage -p 1 nvme0
 155 .Pp
 156 Display a human-readable summary of the nvme0 controller's Error Information Log.
 157 Log pages defined by the NVMe specification include Error Information Log (ID=1),
 158 SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3).
 159 .Pp
 160 .Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0
 161 .Pp
 162 Display a human-readable summary of the nvme0's wdc-specific advanced
 163 SMART data.
 164 .Pp
 165 .Dl nvmecontrol logpage -p 1 -x nvme0
 166 .Pp
 167 Display a hexadecimal dump of the nvme0 controller's Error Information Log.
 168 .Pp
 169 .Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin
 170 .Pp
 171 Print the contents of vendor specific page 0xcb as binary data on
 172 standard out.
 173 Redirect it to a temporary file.
 174 .Pp
 175 .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0
 176 .Pp
 177 Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the
 178 nvme0 controller, but do not activate the image.
 179 .Pp
 180 .Dl nvmecontrol firmware -s 4 -a nvme0
 181 .Pp
 182 Activate the firmware in slot 4 of the nvme0 controller on the next reset.
 183 .Pp
 184 .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0
 185 .Pp
 186 Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the
 187 nvme0 controller and activate it on the next reset.
 188 .Pp
 189 .Dl nvmecontrol power -l nvme0
 190 .Pp
 191 List all the current power modes.
 192 .Pp
 193 .Dl nvmecontrol power -p 3 nvme0
 194 .Pp
 195 Set the current power mode.
 196 .Pp
 197 .Dl nvmecontrol power nvme0
 198 .Pp
 199 Get the current power mode.
 200 .Sh HISTORY
 201 The
 202 .Nm
 203 utility appeared in
 204 .Fx 9.2 .
 205 .Sh AUTHORS
 206 .An -nosplit
 207 .Nm
 208 was developed by Intel and originally written by
 209 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
 210 .Pp
 211 This man page was written by
 212 .An Jim Harris Aq Mt jimharris@FreeBSD.org .