Common

This module contains common commands, that other device classes can support.

squishy.scsi.commands.common.TestUnitReady = <SCSICommand opcode:00 group:0 fields: 2>

Test Unit Ready

This command provides the means to check if the logical unit is ready.

It does not trigger an internal self test on the target.

If the logical unit would accept an appropriate medium-access command without returning a CHECK CONDITION status this command shall return a GOOD status.

squishy.scsi.commands.common.RequestSense = <SCSICommand opcode:03 group:0 fields: 3>

Request Sense

This command requests that the target transfers Sense Data to the initiator.

The sense data shall be valid for a CHECK CONDITION status returned on the prior command. It will also be preserved by the target for the initiator until it is retrieved by the REQUEST SENSE command, or until the receipt of any other command for the same LUN from the initiator that issues the command resulting in the CHECK CONDITION status.

Sense data shall be cleared upon receipt of any subsequent command to the LUN from the initiator receiving the CHECK CONDITION status. In the case of a single initiator the target must assume that the REQUEST SENSES command is from the same initiator.

The AllocLen field specifies the number of bytes that the initiator has allocated for the returned sense data. An allocation length of zero indicates that four bytes of sense data will be transferred. Any other value indicates the maximum number of bytes to be transferred. The target must terminate the DATA IN phase when AllocLen bytes have been sent to the initiator or when all sense data has been exhausted, whichever is less.

The REQUEST SENSE command shall return the CHECK CONDITION status only to report fatal errors for the command. for example:

  1. The target receives a non-zero reserved bit in the command descriptor block.

  2. An unrecovered parity error occurs on the data bus.

  3. A target malfunction prevents the return of sense data.

If any non-fatal error occurs during the execution of the REQUEST SENSE command then the target shall return the sense data with a GOOD status. On fatal errors sense data may be invalid.

A target may implement the non-extended, the extended, or both sense data formats.

Note

Targets that implement both sense data formats may select the non-extended sense data format in response to an allocation length of zero, other methods of selection are also feasible.

The format of the sense data is determined by the error class. Error classes 0 through 6 use the non-extended sense data, error class 7 uses the extended sense data.

The non-extended sense data is depicted below:

Non-extended Sense Data

Byte

7

6

5

4

3

2

1

0

0

AddrValid

Error Class

Error Code

1

Vendor Unique

LBA (MSB)

2

LBA

3

LBA (LSB)

The AddrValid flag indicates that the LBA field contains valid information related to the error code.

The error class specified the class of errors, classes 0 through 6 are all vender unique, the error code for the class is also vendor unique.

For extended sense data, the error class is fixed to 7, but extended sense data will only be returned if the error code is 0. Error code 15 specifies a vendor unique data format for the extended sense data. Error codes 1 tough 14 are reserved.

The extended sense data format is depicted below:

Extended Sense Data

Byte

7

6

5

4

3

2

1

0

0

Valid

1

1

1

0

0

0

0

1

Segment Number

2

File Mark

EOM

ILI

Res

Sense Key

3

Information Byte

4

Information Byte

5

Information Byte

6

Information Byte (LSB)

7

Additional Sense Length (n)

8

to

n+7

Additional Sense Bytes

If Valid is not set, then the data in Information Byte is undefined, otherwise it is defined as follows:

  1. The unsigned LBA associated with the sense key, for type 0, type 4 and type 5 devices.

  2. The difference of the requested length minus the actual length in bytes or blocks. As determined by the command, for type 1, type 2, and type 3 devices.

  3. The difference of the requested number of blocks minus the actual number of blocks copied or compared for the current segment descriptor of a Copy, Compare, or CopyAndVerify command.

The Segment Number field contains the number of the current segment descriptor if the extended sens is in response to a Copy, Compare, or CopyAndVerify command. Up to 256 segments are supported.

The File Mark flag indicates that the current command has read a file mark, and is only used on sequential-access devices.

The EOM or End of Medium flag indicates that an end-of-medium condition (EOT, BOT, Out of paper, etc) exists on a sequential access or printer device. For sequential access devices, this flag indicates that the unit is at or past the early-warning EOT if the direction was forward or that the command could not be completed due to a BOT being encountered if the direction was reverse. Direct access devices must not use this flag, instead they must report attempts to access beyond EOM as an ILLEGAL REQUEST sense key.

The ILI or Incorrect Length Indicator flag indicates that the requested logical block length did not match the logical block length of the data on the medium.

The value of the Sense Key field is described as follows:

Todo

Move this to an enum in command.py

Sense Key

Description

0x0

No Sense. Indicates that there is no specific sense key information to be reported for the designated logical unit. This would be the case for a successful command or a command that received a CHECK CONDITION status due to one of the File Mark, EOM, or ILI flags being set.

0x1

Recovered Error. Indicates that the last command completed successfully with some recovery action performed by the target. Details may be determined by examining the additional sense bytes and information bytes.

0x2

Not Ready. Indicates that the logical unit addressed cannot be accessed. Operator intervention may be required to correct this.

0x3

Medium Error. Indicates that the command terminated with a non-recovered error condition that was likely caused by a flaw in the medium.

0x4

Hardware Error. Indicates that the target detected a non-recoverable hardware failure while performing the command or during a self-test.

0x5

Illegal Request. Indicates that there was an illegal parameter in the command descriptor block or in the additional parameters supplied as data for some commands. If the target detects an invalid parameter in the command descriptor block then it must terminate the command without altering the medium. If the target detects an invalid parameter in the additional parameters supplied as data, then it may alter the medium

0x6

Unit Attention. Indicates that the removable medium may have been changed or the target has been reset.

0x7

Data Protect. Indicates that a command that reads or writes the medium was attempted on a block that is protected, and the op was not done.

0x8

Blank Check. Indicates that a WORM device or a sequential-access device encountered a blank block while reading, or a WORM device encountered a non-blank block while writing.

0x9

Vendor Unique. This sense key is available for reporting vendor unique conditions.

0xA

Copy Aborted. Indicates a Copy, Compare, or CopyAndVerify command was aborted due to an error condition on the source device, destination device, or both.

0xB

Aborted Command. Indicates that the target aborted the command. The initiator may be able to recover by trying the command again.

0xC

Equal. Indicates tha a SearchData command has satisfied an equal comparison.

0xD

Volume Overflow. Indicates that a buffered peripheral device has reached the end-of-medium and data remains in the buffer that has not been written to the medium. A RecoverBufferedData command(s) may be issued to read the unwritten data from the buffer

0xE

Miscompare. Indicates that the source data did not match teh data read from the medium.

0xF

Reserved

The Additional Sense Length specifies how many additional bytes of sense data are to follow. If the allocation length of the command descriptor block is too small to transfer all of the additional data, the Additional Sense Length is NOT adjusted to reflect the truncation.

The Additional Sense Bytes contains data that is command-specific, peripheral-device-specific, or both the further define the nature of the CHECK CONDITION status. The Copy, Compare, CopyAndVerify, and SearchData commands define a standard purpose for some of the bytes. Unless described in said commands, all additional sense bytes are vendor unique.

squishy.scsi.commands.common.Inquiry = <SCSICommand opcode:12 group:0 fields: 3>

Inquiry

This command requests that information regarding parameters of the target and its attached peripheral devices be sent to the initiator.

The AllocLen field specifies the number of bytes that the initiator has allocated for the returned INQUIRY data. An AllocLen of zero indicates that no INQUIRY data shall be transferred to the Initiator, and shall not be considered an error. Any other value indicates the maximum number of bytes that shall be transferred. The target must terminate the DATA IN phase when AllocLen bytes have been transferred or when all available INQUIRY data as been exhausted, which ever is less.

The INQUIRY command must return a CHECK CONDITION status only when the target can not return the requested INQUIRY data.

Note

It is recommended that the INQUIRY data be returned even though the peripheral device may not be ready for other commands.

If an INQUIRY command is received from an initiator with a pending unit attention condition, the target shall perform the INQUIRY command and shall not clear the unit attention condition.

The data returned from the INQUIRY command is described below:

INQUIRY Data

Byte

7

6

5

4

3

2

1

0

0

Peripheral Device Type

1

RMB

Device-Type Qualifier

2

ISO Ver

ECMA Ver

ANSI Ver

3

Reserved

4

Additional Length

5 to n+4

Vendor Unique

The Peripheral Device Type is one of the values in squishy.scsi.device.PeripheralDeviceType

The RMB flag indicates that the medium is removable or not.

The Device-Type Qualifier iss a seven-bit user specified value. This value may be set with any means on the target or peripheral device. SCSI devices that do not support this feature must set it to all zeros (i.e. ``0b0000000``). This feature allows each user to assign a unique value to each specific type of peripheral device that is supported on the system being used. These values may then be used by the self-configuring software to determine what specific peripheral device is at each LUN.

The ISO Ver, and ECMA Ver fields describe to which version of the respective specifications the device compiles to. A zero value in the ISO Ver and/or ECMA Ver fields indicates that the target does not claim compliance to ISO or ECMA Versions of SCSI.

Note

It is possible to claim compliance to more than one standard.

The ANSI Ver field indicates the implemented version of the ANSI SCSI standard with the following values:

Value

Description

0x0

Version is unspecified

0x1

Complies with X3.313:1986

0x2 to 0x7

Reserved

The Additional Length field specifies the length in bytes of the vendor unique parameters. If the AllocLen iss tool small to transfer all of the vendor unique data, the additional length is NOT adjusted to reflect the truncation.

squishy.scsi.commands.common.Copy = <SCSICommand opcode:18 group:0 fields: 3>

Copy

This command provides a means to copy data from one logical unit to itself or another. The logical units may reside on the same SCSI device or different SCSI devices.

Note

Some SCSI devices that implement this command may not support copying to or from another SCSI device, or copies where both logical units reside on another SCSI device.

The ParamLen field specifies the length in bytes of the parameters that are to be sent during the DATA OUT phase of the command. A ParamLen of zero indicates that no data will be transferred, and must not be considered an error.

The COPY parameter list is structured as follows:

COPY Parameter List

Byte

7

6

5

4

3

2

1

0

0

Function Code

Priority

1

Vendor Unique

2

Reserved

3

Reserved

N

Segment descriptors…

The Function Code field defines the specific format for the segment descriptors, they are as follows:

The Priority field establishes the relative priority of the COPY command to other commands being executed by the same target. All other commands are assumed to have a priority of 1, with 0 being the highest priority, the larger the value the lower the priority of the command.

The segment descriptor formats are designated by the Function Code

Device Type

Function Code

Segment Descriptor

Direction

Source

Dest

0x00

0x01

0x00

Segment 1

Direct to Sequential

0x00

0x02

0x00

0x00

0x03

0x00

0x04

0x01

0x00

0x04

0x02

0x00

0x04

0x03

0x00

0x05

0x01

0x00

0x05

0x02

0x00

0x05

0x03

0x00

0x01

0x00

0x01

Segment 1

Sequential to Direct

0x01

0x04

0x01

0x03

0x00

0x01

0x03

0x04

0x01

0x00

0x00

0x02

Segment 2

Direct to Direct

0x00

0x04

0x02

0x04

0x00

0x02

0x04

0x04

0x02

0x05

0x00

0x02

0x05

0x04

0x02

0x01

0x01

0x03

Segment 3

Sequential to Sequential

0x01

0x02

0x03

0x01

0x03

0x03

0x03

0x01

0x03

0x03

0x02

0x03

0x03

0x03

0x03

The Device Type is defined by the values in the squishy.scsi.device.PeripheralDeviceType enum.

The COPY function codes are as follows:

Code

Description

0x00

Direct to Sequential

0x01

Sequential to Direct

0x02

Direct to Direct

0x03

Sequential to Sequential

0x04-0x0F

Reserved

0x10-0x1F

Vendor Unique

Note

There are two general categories of unusual condition that may occur during the execution of a COPY command. THe first one is any unusual condition that are detected by the SCSI target that receives the command and is managing its execution. Examples of such conditions are parity errors, invalid parameters, invalid segment descriptors, and situations where the target is unable to continue operating. In the case of such a condition the target will:

  • Terminate the COPY command with CHECK CONDITION as its status.

  • Return sense data in the extended format. Where the valid bit is set to 1, and the segment descriptor that is currently being processed at the time the condition is detected. The sense key must contain the difference between the number of blocks from the segment descriptor vs the number of blocks that were successfully copied.

The segment descriptor format for copies between direct and sequential access devices are specified below. The descriptor may be repeated up to 256 times within the parameter list as long as it falls within the parameter list length specified in the command descriptor block.

Segment Descriptor for functions 0x00 and 0x01

Byte

7

6

5

4

3

2

1

0

0

Source Address

Reserved

Source LUN

1

Destination Address

Reserved

Destination LUN

2

Sequential-Access Device Block-Length (MSB)

3

Sequential-Access Device Block-Length (LSB)

4

Direct-Access Device Number of Blocks (MSB)

5

Direct-Access Device Number of Blocks

6

Direct-Access Device Number of Blocks

7

Direct-Access Device Number of Blocks (LSB)

8

Direct-Access Device LBA (MSB)

9

Direct-Access Device LBA

10

Direct-Access Device LBA

11

Direct-Access Device LBA (LSB)

The Source Address and Destination Address fields specify the SCSI Device number, and the Source LUN and Destination LUN specify the logical units for the COPY command.

Warning

Some SCSI devices don’t support “third-party” COPY commands, in which the device which is initiating the COPY command is neither the source nor destination of the copy.

Some SCSI devices also only support COPY within itself and not to an external SCSI device.

If an unsupported COPY is requested then the operation is terminated with a CHECK CONDITION status and the sense key is set to ILLEGAL REQUEST.

The Sequential-Access Device Block-Length field specifies the block length to be used on the sequential-access logical unit during this segment of the COPY command.

Segment Descriptor for functions 0x02

Byte

7

6

5

4

3

2

1

0

0

Source Address

Reserved

Source LUN

1

Destination Address

Reserved

Destination LUN

2

Reserved

3

Reserved

4

Source Number of Blocks (MSB)

5

Source Number of Blocks

6

Source Number of Blocks

7

Source Number of Blocks (LSB)

8

Source LBA (MSB)

9

Source LBA

10

Source LBA

11

Source LBA (LSB)

12

Destination LBA (MSB)

13

Destination LBA

14

Destination LBA

15

Destination LBA (LSB)

Segment Descriptor for functions 0x03

Byte

7

6

5

4

3

2

1

0

0

Source Address

Reserved

Source LUN

1

Destination Address

Reserved

Destination LUN

2

Reserved

3

Reserved

4

Source Block Length (MSB)

5

Source Block Length (LSB)

6

Destination Block Length (MSB)

7

Destination Block Length (LSB)

8

Source Number Of Blocks (MSB)

9

Source Number Of Blocks

10

Source Number Of Blocks

11

Source Number Of Blocks (LSB)
squishy.scsi.commands.common.ReceiveDiagnosticResults = <SCSICommand opcode:1C group:0 fields: 3>

Receive Diagnostic Results

Todo

Document this

squishy.scsi.commands.common.SendDiagnostic = <SCSICommand opcode:1D group:0 fields: 7>

Send Diagnostic

Todo

Document this

squishy.scsi.commands.common.Compare = <SCSICommand opcode:19 group:1 fields: 4>

Compare

Todo

Document this

squishy.scsi.commands.common.CopyAndVerify = <SCSICommand opcode:1A group:1 fields: 6>

Copy and Verify

Todo

Document this