Introduction
It has been a number of years since we have addressed the subject of SCSI command compliance testing. This article will describe the details of the latest SCSI Command Compliance Utility tool version 2.0 – an important piece of the STB Suite.
The Purpose of the tool
The purpose of the SCSI Command Compliance Utility is to issue CDB’s to a target device and to record the results of sending the CDB.
The CDB’s which are sent can be “legal” or completely valid CDBs according to the SCSI specification or according to the device manufacturers documentation.
Or the CDB’s issued may be “illegal” or invalid an a number of ways.
A “legal” CDB example is an INQUIRY CDB, which is a 6-byte CDB with a DATA OUT phase with a number of bytes of data returned from the device – in this case 16 bytes. This CDB would look like this:
0x12,00,00,00,0×20,00
An “Illegal” version of this CDB could have a byte with bits set which are specified as reserved bits –
0x12,0xF0,00,00,0×20,00
In addition, a CDB can be defined with a number of “reserved” bits defined in any byte. The Compliance Utility will automatically insert a 1 bit into each reserved bit which has been defined. This lets you with one CDB definition cause a number of CDB’s to be issued, walking the 1 bits through the defined reserved bits.
The Command Compliance utility will issue CDB’s which are defined in a text CDB definition file. If the CDB fails with a CHECK CONDITION the Sense Data will be returned and optionally checked against an expected value. The results will be written to an output log file.
The User Interface
The user interface has input fields to specify the target address of the device, and fields to specify the CDB definition file to use and the file name of the output report.
Enter the drives HBA, Target, and LUN address, then click the Scan button. If the device is found it’s INQUIRY information will be displayed in the Drive Info field.
The CDB file to be used in the test run is named in the CDB File field, and the name of the output report file is named in the Results field.
The CDB Definition File
You can create as many CDB definition files as you need. As an example, you could have one CDB file which only issues “non-destructive” CDB’s – Reads but no Writes or Formats for instance.
Or you could have one CDB file of legal disk commands and another with illegal disk commands, others for tape commands, others for vendor unique commands.
Each CDB file can contain definitions of up to 200 CDBs.
Each line of the CDB file consists of the same pattern of fields:
“CDB length, Data Direction, Transfer length, CDB fields, [Command Title], Expected Sense Key, Expected Sense Code, Expected ASQ ”
The CDB length is the number of bytes in the CDB, and must be 6, 10, or 12.
The Data Direction is 00 for Data Out or 01 for Data In.
The Transfer length is the bytes in hex to transfer. This field is limited to 3 digits.
The CDB fields consist of the standard CDB as specified in SCSI CDB layouts. However, the byte(s) corresponding to reserved bits of the CDB have a special format in the fields of the CDB file to allow masking of the reserved bits to test compliance.
The mask is specified with the pattern “|hh” where hh represents two hex digits that specify the reserved bits. For example, if bits 1 through 4 are reserved in a particular CDB then the mask is |1E. The location of the mask is specified immediately after the standard CDB byte that contains the reserved bits that need to be examined. For example, the Inquiry command has reserved bits 1 through 4 in byte 1 of the CDB. The total mask assuming logical unit zero, looks like “00|1E”. If a mask is specified, each bit in the mask is “OR”- ed with the bits in the standard CDB byte during the compliance test.
The Command Title is the name you wanted printed for this CDB in the report file. It must be surrounded by “[ ]” – for example [10-Byte Read]
The Expected Sense Key, Code, and ASQ fields are optional. If you do include expected sense data it should be entered as hexadecimal numbers, such as 05,24,00.
Here is an example of a CDB file with three entries:
"## DISK ##"
"06,01,200,08,00,00,00,01,00,[READ],05,24,00"
"10,01,200,28,00,00,00,00,00,00,00,01,00,[EXTENDED READ],05,20,00"
"06,01,00,00,00|1F,00|FF,00|FF,00|FF,00,[ILLEGAL-REZERO],05,26,00"
The first line “## DISK ##” is the title and will be printed at the top of the output report.
The next line defines a 6-byte READ CDB. It defines that there will be 0x200 bytes of DATA IN and that the expected Sense data in case of a CHECK CONDITION is 05/24/00
The last CDB entry defines a CDB with reserved bits.
"06,01,00,00,00|1F,00|FF,00|FF,00|FF,00,[ILLEGAL-REZERO],05,26,00"
The bold section in the above CDB says to walk a 1 through all bit positions between 00 and 0x1f of that CDB byte. The next byte is the same but defines to walk the 1 from 00 through 0xff, in other words through all bit positions of that byte.
To help make this action clearer here is a section of the output file that is generated with this CDB definition:
"CDB[ILLEGAL-REZERO]= 00,00,00,00,00,00 passed"
"CDB[ILLEGAL-REZERO]= 00,01,00,00,00,00 failed Sense = 05/24/00 Expected 5/26/0 MISMATCH"
"CDB[ILLEGAL-REZERO]= 00,02,00,00,00,00 failed Sense = 05/24/00 Expected 5/26/0 MISMATCH"
"CDB[ILLEGAL-REZERO]= 00,04,00,00,00,00 failed Sense = 05/24/00 Expected 5/26/0 MISMATCH"
"CDB[ILLEGAL-REZERO]= 00,08,00,00,00,00 failed Sense = 05/24/00 Expected 5/26/0 MISMATCH"
"CDB[ILLEGAL-REZERO]= 00,10,00,00,00,00 failed Sense = 05/24/00 Expected 5/26/0 MISMATCH"
"CDB[ILLEGAL-REZERO]= 00,00,01,00,00,00 failed Sense = 05/24/00 Expected 5/26/0 MISMATCH"
"CDB[ILLEGAL-REZERO]= 00,00,02,00,00,00 failed Sense = 05/24/00 Expected 5/26/0 MISMATCH"
.
.
.
As the bold red numbers show, a 1 bit is walked through each reserved bit position of CDB byte 1, then byte 2, etc.
The Output Report
A standard text file is generated for each run of the utility. Here is an example of a disk test output:
"SCSI Command Compliance Test Version 2.0 120620"
"SCSI device tested = Adapter = 7 , Target = 0 ,LUN = 0"
"Vendor = SEAGATE , Product = ST3450857SS , Revision = ES62"
" "
"## DISK ##"
"CDB[READ]= 08,00,00,00,01,00 passed"
""
"CDB[EXTENDED READ]= 28,00,00,00,00,00,00,00,01,00 passed"
""
"CDB[WRITE]= 0A,00,00,00,01,00 passed"
""
"CDB[EXTENDED WRITE]= 2A,00,00,00,00,00,00,00,00,00 passed"
"CDB[CHANGE DEFINITION]= 40,00,00,00,00,00,00,00,00,00 failed Sense = 05/20/00 Expected 5/20/0 OK"
""
"CDB[COMPARE]= 39,00,00,00,00,00,00,00,00,00 failed Sense = 05/20/00 Expected 5/20/0 OK"
"
"CDB[SEND DIAGNOSTIC]= 1D,00,00,00,00,00 failed Sense = 05/24/00 Expected 5/20/0 MISMATCH"
Note: if the CDB definition file entry has Expected Sense Key, Expected Sense Code, and Expected ASQ defined, and a CHECK CONDITION occurs, the actual sense data and the expected sense data will be logged, along with either “MISMATCH” or “OK” depending on if the expected sense data is what was generated.
Summary
The CDB Compliance Utility is extremely versatile, allowing any CDBs to be issued and results collected from any type of SCSI, SAS, or Fibre Channel device. Since the utility uses simple text files to define the CDB’s to be executed the utility will never become out of date as CDB definition files containing any number of CDBs (up to 200 per file) can be defined.
Another advantage of having text files to define the CDB’s to test is that like types of CDBs can be grouped together. Disk oriented CDBs, tape oriented CDBs, etc. Also, separate CDB files can be created for CDBs which are “destructive” (write to the drive, format, etc) versus files with only non-destructive commands.