Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NVMECONTROL(8)		FreeBSD	System Manager's Manual		NVMECONTROL(8)

     nvmecontrol -- NVM	Express	control	utility

     nvmecontrol devlist
     nvmecontrol identify [-v] [-x] <device id>	<namespace id>
     nvmecontrol perftest <-n num_threads> <-o read|write> [-p]
		 <-s size_in_bytes> <-t	time_in_sec> <namespace	id>
     nvmecontrol reset <controller id>
     nvmecontrol logpage <-p page_id> [-x] [-v vendor-string] [-b] [-f LSP]
		 [-i LSI] [-r] <device id> <namespace id>
     nvmecontrol ns active <device id>
     nvmecontrol ns allocated <device id>
     nvmecontrol ns attach <-n nsid> <-c cntid>	<device	id>
     nvmecontrol ns attached <-n nsid> <device id>
     nvmecontrol ns controllers	<device	id>
     nvmecontrol ns create <-s nsze> [-c ncap] [-f lbaf] [-m mset] [-n nmic]
		 [-p pi] [-l pil] [-L flbas] [-d dps] <device id>
     nvmecontrol ns delete <-n nsid> <device id>
     nvmecontrol ns detach <-n nsid> <-c cntid>	<device	id>
     nvmecontrol ns identify [-v] [-x] <-n nsid> <device id>
     nvmecontrol nsid <device id> <namespace id>
     nvmecontrol resv acquire <-c crkey> [-p prkey] <-t	rtype> <-a racqa>
		 <namespace id>
     nvmecontrol resv register [-c crkey] <-k nrkey> <-r rrega>	[-i iekey]
		 [-p cptpl] <namespace id>
     nvmecontrol resv release <-c crkey> <-t rtype> <-a	rrela> <namespace id>
     nvmecontrol resv report [-e] [-v] [-x] <namespace id>
     nvmecontrol firmware [-s slot] [-f	path_to_firmware] [-a] <device id>
     nvmecontrol format	[-f fmt] [-m mset] [-o pi] [-l pil] [-E] [-C]
		 <device id> <namespace	id>
     nvmecontrol sanitize <-a sanact> [-c owpass] [-d] [-p ovrpat] [-r]	[-I]
		 [-U] <device id>
     nvmecontrol power [-l] [-p	-power_state] [-w -workload_hint]
     nvmecontrol wdc cap-diag [-o -path_template] <device id>
     nvmecontrol wdc drive-log [-o -path_template] <device id>
     nvmecontrol wdc get-crash-dump [-o	-path_template]	<device	id>

     NVM Express (NVMe)	is a storage protocol standard,	for SSDs and other
     high-speed	storage	devices	over PCI Express.

     The logpage command knows how to print log	pages of various types.	 It
     also knows	about vendor specific log pages	from hgst/wdc and intel.  Note
     that some vendors use the same log	page numbers for different data.

     Page 0x01	Drive Error Log
     Page 0x02	Health/SMART Data
     Page 0x03	Firmware Information
     Page 0x04	Changed	Namespace List
     Page 0x05	Commands Supported and Effects
     Page 0x80	Reservation Notification
     Page 0x81	Sanitize Status
     Page 0xc1	Advanced SMART information (WDC/HGST)
     Page 0xc1	Read latency stats (Intel)
     Page 0xc2	Wite latency stats (Intel)
     Page 0xc5	Temperature stats (Intel)
     Page 0xca	Advanced SMART information (Intel)

     Specifying	-v help	will list all valid vendors and	pages.	-x will	print
     the page as hex.  -b will print the binary	data for the page.  -s will
     set Log Specific Field.  -i will set Log Specific Identifier.  -r will
     set Retain	Asynchronous Event.

     Various namespace management commands.  If	namespace management is	sup-
     ported by device, allow list, create and delete namespaces, list, attach
     and detach	controllers to namespaces.

   resv	acquire
     Acquire or	preempt	namespace reservation, using specified parameters:

     -a	     Acquire action:
	     0	     Acquire
	     1	     Preempt
	     2	     Preempt and abort

     -c	     Current reservation key.

     -p	     Preempt reservation key.

     -t	     Reservation type:
	     1	     Write Exclusive
	     2	     Exclusive Access
	     3	     Write Exclusive - Registrants Only
	     4	     Exclusive Access -	Registrants Only
	     5	     Write Exclusive - All Registrants
	     6	     Exclusive Access -	All Registrants

   resv	register
     Register, unregister or replace reservation key, using specified parame-

     -c	     Current reservation key.

     -k	     New reservation key.

     -r	     Register action:
	     0	     Register
	     1	     Unregister
	     2	     Replace

     -i	     Ignore Existing Key

     -p	     Change Persist Through Power Loss State:
	     0	     No	change to PTPL state
	     2	     Set PTPL state to a0a.  Reservations are released and
		     registrants are cleared on	a power	on.
	     3	     Set PTPL state to a1a.  Reservations and registrants per-
		     sist across a power loss.

   resv	release
     Release or	clear reservation, using specified parameters:

     -c	     Current reservation key.

     -t	     Reservation type.

     -a	     Release action:
	     0	     Release
	     1	     Clean

   resv	report
     Print reservation status, using specified parameters:

     -x	     Print reservation status in hex.

     -e	     Use Extended Data Structure.

     Format either specified namespace,	or all namespaces of specified con-
     troller, using specified parameters: fmt LBA Format, mset Metadata	Set-
     tings, pi Protection Information, pil Protection Information Location.
     When formatting specific namespace, existing values are used as defaults.
     When formatting all namespaces, all parameters should be specified.  Some
     controllers may not support formatting or erasing specific	or all name-
     spaces.  Option -E	enables	User Data Erase	during format.	Option -C en-
     ables Cryptographic Erase during format.

     Sanitize NVM subsystem of specified controller, using specified parame-

     -a	operation
	     Specify the sanitize operation to perform.

	     overwrite	       Perform an overwrite operation by writing a
			       user supplied data pattern to the device	one or
			       more times.  The	pattern	is given by the	-p ar-
			       gument.	The number of times is given by	the -c

	     block	       Perform a block erase operation.	 All the de-
			       vice's blocks are set to	a vendor defined
			       value, typically	zero.

	     crypto	       Perform a cryptographic erase operation.	 The
			       encryption keys are changed to prevent the de-
			       cryption	of the data.

	     exitfailure       Exits a previously failed sanitize operation.
			       A failed	sanitize operation can only be exited
			       if it was run in	the unrestricted completion
			       mode, as	provided by the	-U argument.

     -c	passes
	     The number	of passes when performing an `overwrite' operation.
	     Valid values are between 1	and 16.	 The default is	1.

     -d	     No	Deallocate After Sanitize.

     -I	     When performing an	`overwrite' operation, the pattern is inverted
	     between consecutive passes.

     -p	pattern
	     32	bits of	pattern	to use when performing an `overwrite' opera-
	     tion.  The	pattern	is repeated as needed to fill each block.

     -U	     Perform the sanitize in the unrestricted completion mode.	If the
	     operation fails, it can later be exited with the `exitfailure'

     -r	     Run in "report only" mode.	 This will report status on a sanitize
	     that is already running on	the drive.

     The various wdc command retrieve log data from the	wdc/hgst drives.  The
     -o	flag specifies a path template to use to output	the files.  Each file
     takes the path template (which defaults to	nothing), appends the drive's
     serial number and the type	of dump	it is followed by .bin.	 These logs
     must be sent to the vendor	for analysis.  This tool only provides a way
     to	extract	them.

	   nvmecontrol devlist

     Display a list of NVMe controllers	and namespaces along with their	device

	   nvmecontrol identify	nvme0

     Display a human-readable summary of the nvme0 IDENTIFY_CONTROLLER data.

	   nvmecontrol identify	-x -v nvme0ns1

     Display an	hexadecimal dump of the	nvme0 IDENTIFY_NAMESPACE data for
     namespace 1.

	   nvmecontrol perftest	-n 32 -o read -s 512 -t	30 nvme0ns1

     Run a performance test on nvme0ns1	using 32 kernel	threads	for 30 sec-
     onds.  Each thread	will issue a single 512	byte read command.  Results
     are printed to stdout when	30 seconds expires.

	   nvmecontrol reset nvme0

     Perform a controller-level	reset of the nvme0 controller.

	   nvmecontrol logpage -p 1 nvme0

     Display a human-readable summary of the nvme0 controller's	Error Informa-
     tion Log.	Log pages defined by the NVMe specification include Error In-
     formation Log (ID=1), SMART/Health	Information Log	(ID=2),	and Firmware
     Slot Log (ID=3).

	   nvmecontrol logpage -p 0xc1 -v wdc nvme0

     Display a human-readable summary of the nvme0's wdc-specific advanced
     SMART data.

	   nvmecontrol logpage -p 1 -x nvme0

     Display a hexadecimal dump	of the nvme0 controller's Error	Information

	   nvmecontrol logpage -p 0xcb -b nvme0	> /tmp/page-cb.bin

     Print the contents	of vendor specific page	0xcb as	binary data on stan-
     dard out.	Redirect it to a temporary file.

	   nvmecontrol firmware	-s 2 -f	/tmp/nvme_firmware nvme0

     Download the firmware image contained in "/tmp/nvme_firmware" to slot 2
     of	the nvme0 controller, but do not activate the image.

	   nvmecontrol firmware	-s 4 -a	nvme0

     Activate the firmware in slot 4 of	the nvme0 controller on	the next re-

	   nvmecontrol firmware	-s 7 -f	/tmp/nvme_firmware -a nvme0

     Download the firmware image contained in "/tmp/nvme_firmware" to slot 7
     of	the nvme0 controller and activate it on	the next reset.

	   nvmecontrol power -l	nvme0

     List all the current power	modes.

	   nvmecontrol power -p	3 nvme0

     Set the current power mode.

	   nvmecontrol power nvme0

     Get the current power mode.

     The directories /lib/nvmecontrol and /usr/local/lib/nvmecontrol are
     scanned for any .so files.	 These files are loaded.  The members of the
     top linker	set are	added to the top-level commands.  The members of the
     logpage linker set	are added to the logpage parsers.

     The nvmecontrol utility appeared in FreeBSD 9.2.

     nvmecontrol was developed by Intel	and originally written by Jim Harris

     This man page was written by Jim Harris <>.

FreeBSD	13.0			August 5, 2019			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help