diff options
Diffstat (limited to 'inhex/README')
| -rw-r--r-- | inhex/README | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/inhex/README b/inhex/README new file mode 100644 index 00000000..77557a05 --- /dev/null +++ b/inhex/README @@ -0,0 +1,94 @@ + 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 |