xref: /aosp_15_r20/external/sg3_utils/inhex/README (revision 44704f698541f6367e81f991ef8bb54ccbf3fc18)

        Hex data for various sg3_utils utilities
        ========================================

The files in this folder contain hexadecimal data (in ASCII) and associated
comments (prefixed with the hash mark symbol: '#' ). Files containing
hexadecimal data have the extension ".hex". There is at least one file
containing binary data and it has the extension ".raw".

The utility that each hex file is associated with can be determined in most
case by prepending "sg_" to these filenames. Then go to the 'src' folder (a
sibling folder to this one) and look for a match or partial match on
the name.

For example:
    vpd_dev_id.hex
after prepending 'sg_' becomes:
    sg_vpd_dev_id.hex
which is a partial match on the sg_vpd utility.
The remaining 'dev_id.hex' is meant to suggest the 'device identifier'
VPD page which is a mandatory VPD page for SCSI devices..

Assuming sg3_utils is installed, it can be tested like this:
    sg_vpd --inhex=<folder_holding_sg3_utils>/inhex/vpd_dev_id.hex

And should output this:

Device Identification VPD page:
  Addressed logical unit:
    designator type: NAA,  code set: Binary
      0x5000c5003011cb2b
  Target port:
    designator type: NAA,  code set: Binary
     transport: Serial Attached SCSI Protocol (SPL-4)
      0x5000c5003011cb29
    designator type: Relative target port,  code set: Binary
     transport: Serial Attached SCSI Protocol (SPL-4)
      Relative target port: 0x1
  Target device that contains addressed lu:
    designator type: NAA,  code set: Binary
     transport: Serial Attached SCSI Protocol (SPL-4)
      0x5000c5003011cb28
    designator type: SCSI name string,  code set: UTF-8
      SCSI name string:
      naa.5000C5003011CB28

Not all the hex files follow the "prepend sg_" pattern. Those hex files
starting with 'nvme_' are examples of invoking NVMe commands with the
sg_raw utility.

Binary <--> Hexadecimal
-----------------------
The vpd_zbdc.raw file is binary and was created by:
    sg_decode_sense --inhex=vpd_zbdc.hex --nodecode --write=vpd_zbdc.raw
as an example of converting a file in ASCII hexadecimal byte oriented
format to binary.

Turning binary output into hexadecimal can be done several ways. For
viewing in byte oriented ASCII hex these Unix commands can be used:
    od -t x1 vpd_zbdc.raw
    hexdump -C vpd_zbdc.raw

Each line starting with a "input offset" which is a running count of
bytes, starting at zero. The hexdump examples shows an ASCII rendering
of those 16 bytes to the right of each line. The sg_decode_sense utility
may also be used:
    sg_decode_sense --binary=vpd_zbdc.raw -H
    sg_decode_sense --binary=vpd_zbdc.raw -HH

The second form of sg_decode_sense appends an ASCII rendering of the 16
bytes to the right of each line.

When ASCII hexadecimal is being used as input to a utility in this
package, the "input offset" at the start of each line (and the optional
ASCII rendering to the right of each line) must not be given.
That can be done with hexdump:
   hexdump -An -C -v vpd_zbdc.raw
           ^^^
That is a syntax error, there is no 'A' option <<<<<<<< check

And the sg_decode_sense utility can do it with (with the --nodecode option):
   sg_decode_sense -N --binary=vpd_zbdc.raw -HHH
That will print suitable lines of hexadecimal (16 bytes per line) to the
console (stdout) To go the other way (i.e. hexadecimal to binary):
   sg_decode_sense -N --inhex=vpd_zbdc.hex --write=vpd_zbdc.bin


Conclusion
----------
Users are encouraged to send the author any ASCII hex files for utilities
that support --inhex and don't have hex data already. Special cases are
also welcome. They help the author test this code.

Douglas Gilbert
18th July 2022