summaryrefslogtreecommitdiffstats
path: root/Documentation/nvme-get-log.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/nvme-get-log.txt')
-rw-r--r--Documentation/nvme-get-log.txt137
1 files changed, 137 insertions, 0 deletions
diff --git a/Documentation/nvme-get-log.txt b/Documentation/nvme-get-log.txt
new file mode 100644
index 0000000..98b1f9c
--- /dev/null
+++ b/Documentation/nvme-get-log.txt
@@ -0,0 +1,137 @@
+nvme-get-log(1)
+===============
+
+NAME
+----
+nvme-get-log - Retrieves a log page from an NVMe device
+
+SYNOPSIS
+--------
+[verse]
+'nvme get-log' <device> [--log-id=<log-id> | -i <log-id>]
+ [--log-len=<log-len> | -l <log-len>]
+ [--aen=<aen> | -a <aen>]
+ [--namespace-id=<nsid> | -n <nsid>]
+ [--raw-binary | -b]
+ [--lpo=<offset> | -L <offset>]
+ [--lsp=<field> | -s <field>]
+ [--lsi=<field> | -S <field>]
+ [--rae | -r]
+ [--csi=<command_set_identifier> | -y <command_set_identifier>]
+ [--ot=<offset_type> | -O <offset_type>]
+ [--xfer-len=<length> | -x <length>]
+ [--output-format=<fmt> | -o <fmt>] [--verbose | -v]
+
+DESCRIPTION
+-----------
+Retrieves an arbitrary NVMe log page from an NVMe device and provides
+the returned structure.
+
+The <device> parameter is mandatory and may be either the NVMe character
+device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1).
+
+On success, the returned log structure may be returned in one of several
+ways depending on the option flags; the structure may be displayed in
+hex by the program or the raw buffer may be printed to stdout for another
+program to parse.
+
+OPTIONS
+-------
+-l <log-len>::
+--log-len=<log-len>::
+ Allocates a buffer of <log-len> bytes size and requests this
+ many bytes be returned in the constructed NVMe command. This
+ param is mandatory.
+
+-i <log-id>::
+--log-id=<log-id>::
+ Sets the commands requested log-id to <log-id>. Defaults to 0.
+
+-a <aen>::
+--aen=<aen>::
+ Convenience field for extracting log information based on an
+ asynchronous event notification result. This will override log-id and
+ log-len, if set.
+
+-n <nsid>::
+--namespace-id=<nsid>::
+ Sets the command's nsid value to the given nsid. Defaults to
+ 0xffffffff if not given. This option may not affect anything
+ depending on the log page, which may or may not be specific to
+ a namespace.
+
+-b::
+--raw-binary::
+ Print the raw log buffer to stdout.
+
+-L <offset>::
+--lpo=<offset>::
+ The log page offset specifies the location within a log page to start
+ returning data from. It's Dword-aligned and 64-bits.
+
+-s <field>::
+--lsp=<field>::
+ The log specified field of LID.
+
+-S <field>::
+--lsi=<field>::
+ The log specified field of Log Specific Identifier.
+
+-r::
+--rae::
+ Retain an Asynchronous Event.
+
+-y <command_set_identifier>::
+--csi=<command_set_identifier>::
+ This field specifies the identifier of command set.
+ if not issued, NVM Command Set will be selected.
+
+-O::
+--ot::
+ This field specifies the offset type. If set to false, the
+ Log Page Offset Lower field and the Log Page Offset Upper
+ field specify the byte offset into the log page to be returned.
+ If set to true, the Log Page Offset Lower field and the Log
+ Page Offset Upper field specify the index into the list of
+ data structures in the log page to be returned.
+ The default is byte offset. If the option is specified
+ the index mode is used.
+
+-x <length>::
+--xfer-len <length>:
+ Specify the read chunk size. The length argument is expected to be
+ a multiple of 4096. The default size is 4096.
+
+-o <fmt>::
+--output-format=<fmt>::
+ Set the reporting format to 'normal', 'json' or 'binary'. Only one
+ output format can be used at a time.
+
+-v::
+--verbose::
+ Increase the information detail in the output.
+
+EXAMPLES
+--------
+* Get 512 bytes from log page 2
++
+------------
+# nvme get-log /dev/nvme0 --log-id=2 --log-len=512
+------------
++
+The above example will get log page 2 (SMART), and request 512
+bytes. On success, the returned log will be dumped in hex and not
+interpreted by the program.
+
+* Have the program return the raw log page in binary:
++
+------------
+# nvme get-log /dev/nvme0 -log-id=2 --log-len=512 --raw-binary > log_page_2.raw
+# nvme get-log /dev/nvme0 -i 2 -l 512 -b > log_page_2.raw
+------------
++
+It is not a good idea to not redirect stdout when using this mode.
+
+NVME
+----
+Part of the nvme-user suite