major rework of lib/sg_pt_freebsd.c; sg_raw: fix prints of NVMe NVM command names

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@896 6180dd3e-e324-4e3e-922d-17de1ae2f315

2 files changed, 50 insertions, 2 deletions

diff --git a/inhex/nvme_read_ctl.hex b/inhex/nvme_read_ctl.hex
index 397072d8..1473d410 100644
--- a/inhex/nvme_read_ctl.hex
+++ b/inhex/nvme_read_ctl.hex
@@ -11,7 +11,7 @@
 #    fffffffe                  use byte length of data-in buffer
 #    fffffffd                  use byte length of data-out buffer
 #
-# 512 byte logical block size is assumed. Read 4 blocks hence 2048bytes.
+# 512 byte logical block size is assumed. Read 4 blocks hence 2048 bytes.
 # The first LBA read is 0x12345 and the namespace is 1. If successful
 # the four blocks will be read into the data-in buffer. Submission queu
 # 0 is used (the same queue that Admin commands use). The NVM opcode for
@@ -27,7 +27,8 @@
 #
 # A typical invocation in Linux and FreeBSD would look like this:
 #    sg_raw --cmdfile=nvme_read_ctl.hex --nvm -r 2048
-#           --outfile=t.bin /dev/nvme0
+#           --outfile=t.bin /dev/nvme0n1
+# In FreeBSD the device name would be /dev/nvme0ns1
 #
 # Notice the '--nvm' option which is needed to distiguish a NVM
 # command from an Admin command as Admin commands are the default
diff --git a/inhex/nvme_read_oob_ctl.hex b/inhex/nvme_read_oob_ctl.hex
new file mode 100644
index 00000000..13b0b118
--- /dev/null
+++ b/inhex/nvme_read_oob_ctl.hex
@@ -0,0 +1,47 @@
+# 64 byte NVMe, Read command (a NVM command) which what should be an
+# Out-of-Bounds LBA (around 377 TB with 512 byte sectors. This file is
+# suitable for:
+#       sg_raw --cmdfile=<this_file_name> --nvm --request=2048 <nvme_device>
+#
+# The address field (at byte offset 24, 8 bytes and little endian) gives
+# special meaning to the highest address pointers:
+#    ffffffff fffffffe         use address of data-in buffer
+#    ffffffff fffffffd         use address of data-out buffer
+#
+# The data length field (at byte offset 36, 4 bytes and little endian)
+# gives special meaning to the highest block counts:
+#    fffffffe                  use byte length of data-in buffer
+#    fffffffd                  use byte length of data-out buffer
+#
+# vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
+# This NVMe (NVM) Read command purposely has a very large starting LBA
+# in order to get a "Attempted write to read only range" error. This is
+# to test error reporting.
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#
+# 512 byte logical block size is assumed. Read 4 blocks hence 2048 bytes.
+# The first LBA read is 0xabcd012345 and the namespace is 1. If successful
+# the four blocks will be read into the data-in buffer. Submission queu
+# 0 is used (the same queue that Admin commands use). The NVM opcode for
+# the Read command is 0x2 and appears in the first command byte.
+
+02 00 00 00 01 00 00 00  00 00 00 00 00 00 00 00
+00 00 00 00 00 00 00 00  fe ff ff ff ff ff ff ff
+00 00 00 00 fe ff ff ff  45 23 01 cd ab 00 00 00
+03 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00
+
+# Notice NVMe uses its quirky "0's based" number of blocks so
+# 03 appears at byte offset 48 to mean "read 4 blocks".
+#
+# A typical invocation in Linux and FreeBSD would look like this:
+#    sg_raw --cmdfile=nvme_read_oob_ctl.hex --nvm -r 2048
+#           --outfile=t.bin /dev/nvme0n1
+# In FreeBSD the device name would be /dev/nvme0ns1
+#
+# Notice the '--nvm' option which is needed to distiguish a NVM
+# command from an Admin command as Admin commands are the default
+# in this utility.
+#
+# This utility (and most others in the package) aligns data-in and
+# data-out buffers to the beginning of pages which are 4096 bytes
+# long at a minimum. This is the way NVMe likes things as well.