inhex/README - main - githubmirror/sg3_utils

inhex/README
101 строка4 KB
Douglas Gilbert
scsi-rescan.8 manpage: fix error in Makefile.am
05 май 2026, 05:29
05 май 2026, 05:2958cde35
        Hex data for various sg3_utils utilities
        ========================================

The files in this folder contain hexadecimal data (in ASCII) and associated
comments. Comments start with the hash mark symbol: '#' and extend to the
end of that line. 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
cases by prepending "sg_" to those filenames. The beginning of such a
filename should match an executable whose source should be found in the
'src' sibling directory.

For example:
    vpd_dev_id.hex
after prepending 'sg_' the filename 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 that the 'device identifier'
VPD page is what is being represented. The 'device identifier' VPD page is
mandatory for SCSI devices since SPC-2 (INCITS 351-2001).

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 starts with a "input offset" which is a running count of
bytes, starting at zero. The hexdump example 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 -v -e '16/1 "%02x " "\n"'  vpd_zbdc.raw

Strange that hexdump can't display unadorned ASCII hex bytes without a
special formatting string.

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

The author has a hexdump-like utility called hxasdmp whose source and
manpage is the utils directory (a sibling of this directory. hxascdmp and
its manpage are not normally installed. hxascdmp is purely byte-oriented.


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
4th May 2026