From f26f66d866ba1a9f3204e6fdfe2b07e67b5492ad Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Wed, 10 Apr 2024 21:41:32 +0200
Subject: Adding upstream version 2.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 Documentation/nvme-get-log.txt | 137 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 Documentation/nvme-get-log.txt

(limited to 'Documentation/nvme-get-log.txt')

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
-- 
cgit v1.2.3