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 4, 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 .Ss wdc
 112 The various wdc command retrieve log data from the wdc/hgst drives.
 113 The
 114 .Fl o
 115 flag specifies a path template to use to output the files.
 116 Each file takes the path template (which defaults to nothing), appends
 117 the drive's serial number and the type of dump it is followed
 118 by .bin.
 119 These logs must be sent to the vendor for analysis.
 120 This tool only provides a way to extract them.
 121 .Sh EXAMPLES
 122 .Dl nvmecontrol devlist
 123 .Pp
 124 Display a list of NVMe controllers and namespaces along with their device nodes.
 125 .Pp
 126 .Dl nvmecontrol identify nvme0
 127 .Pp
 128 Display a human-readable summary of the nvme0 IDENTIFY_CONTROLLER data.
 129 .Pp
 130 .Dl nvmecontrol identify -x -v nvme0ns1
 131 .Pp
 132 Display an hexadecimal dump of the nvme0 IDENTIFY_NAMESPACE data for namespace
 133 1.
 134 .Pp
 135 .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1
 136 .Pp
 137 Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds.  Each
 138 thread will issue a single 512 byte read command.  Results are printed to
 139 stdout when 30 seconds expires.
 140 .Pp
 141 .Dl nvmecontrol reset nvme0
 142 .Pp
 143 Perform a controller-level reset of the nvme0 controller.
 144 .Pp
 145 .Dl nvmecontrol logpage -p 1 nvme0
 146 .Pp
 147 Display a human-readable summary of the nvme0 controller's Error Information Log.
 148 Log pages defined by the NVMe specification include Error Information Log (ID=1),
 149 SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3).
 150 .Pp
 151 .Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0
 152 .Pp
 153 Display a human-readable summary of the nvme0's wdc-specific advanced
 154 SMART data.
 155 .Pp
 156 .Dl nvmecontrol logpage -p 1 -x nvme0
 157 .Pp
 158 Display a hexadecimal dump of the nvme0 controller's Error Information Log.
 159 .Pp
 160 .Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin
 161 .Pp
 162 Print the contents of vendor specific page 0xcb as binary data on
 163 standard out.
 164 Redirect it to a temporary file.
 165 .Pp
 166 .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0
 167 .Pp
 168 Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the
 169 nvme0 controller, but do not activate the image.
 170 .Pp
 171 .Dl nvmecontrol firmware -s 4 -a nvme0
 172 .Pp
 173 Activate the firmware in slot 4 of the nvme0 controller on the next reset.
 174 .Pp
 175 .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0
 176 .Pp
 177 Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the
 178 nvme0 controller and activate it on the next reset.
 179 .Pp
 180 .Dl nvmecontrol power -l nvme0
 181 .Pp
 182 List all the current power modes.
 183 .Pp
 184 .Dl nvmecontrol power -p 3 nvme0
 185 .Pp
 186 Set the current power mode.
 187 .Pp
 188 .Dl nvmecontrol power nvme0
 189 .Pp
 190 Get the current power mode.
 191 .Sh AUTHORS
 192 .An -nosplit
 193 .Nm
 194 was developed by Intel and originally written by
 195 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
 196 .Pp
 197 This man page was written by
 198 .An Jim Harris Aq Mt jimharris@FreeBSD.org .