ASPI SPECIFICATION ADDENDUM FEBRUARY 1994 Introduction Adaptec has made minor additions to the ASPI specification to give greater flexibility to ASPI modules. The main addition is support for residual byte length reporting. What is residual byte length? Residual byte length is the number of bytes not transferred to, or received from, the target SCSI device. For example, if the ASPI buffer length for a SCSI Inquiry command is set for 100 bytes, but the target only returns back 36 bytes, this makes for a residual length of 64 bytes. Another example, if the ASPI buffer length for a SCSI write command is set for 514 bytes, but the target only takes 512 bytes, this makes for a residual length of 2 bytes. How do I find out if the ASPI manager loaded supports this new feature? ASPI modules can determine if the loaded ASPI manager supports residual byte length by issuing an Extended Host Adapter Inquiry command. If you refer to the current ASPI for DOS specification, the standard Host Adapter Inquiry command is as follows: NOTE: The following discussion assumes you are already familiar with sending an ASPI Host Adapter Inquiry command to an ASPI manager. OFFSET# BYTES DESCRIPTION R/W 00h (00) 01h (01) Command Code = 0 W 01h (01) 01h (01) Status R 02h (02) 01h (01) Host Adapter Number W 03h (03) 01h (01) SCSI Request Flags W 04h (04) 04h (04) Reserved for Expansion = 0 - 08h (08) 01h (01) # of Host Adapters R 09h (09) 01h (01) Target ID of Host Adapter R 0Ah (10) 10h (16) SCSI Manager ID R 1Ah (26) 10h (16) Host Adapter ID R 2Ah (42) 10h (16) Host Adapter Unique Parameters R The Extended Host Adapter Inquiry command is defined as follows: OFFSET # BYTES DESCRIPTION R/W 00h (00) 01h (01) Command Code = 0 W 01h (01) 01h (01) Status R 02h (02) 01h (01) Host Adapter Number W 03h (03) 01h (01) SCSI Request Flags W 04h (04) 01h (01) Extended Request Signature = 55h R/W 05h (05) 01h (01) Extended Request Signature = AAh R/W 06h (06) 01h (01) Length of Extended Buffer (N),Low Byte R/W 07h (07) 01h (01) Length of Extended Buffer (N),High Byte R/W 08h (08) 01h (01) # of Host Adapters R 09h (09) 01h (01) Target ID of Host Adapter R 0Ah (10) 10h (16) SCSI Manager ID R 1Ah (26) 10h (16) Host Adapter ID R 2Ah (42) 10h (16) Host Adapter Unique Parameters R 3Ah (58) N Extended Buffer R The user places the AA55h in bytes #4-5 of the structure. The Extended Buffer length (N) also needs to be initialized to the size of the extended buffer. A typical value would be 4. If the ASPI manager that is passed this new extended structure supports the Extended Host Adapter Inquiry command, the AA55h bytes will be flipped around to 55AAh. If this does not occur, the caller should assume that the ASPI manager does not support residual byte length or any of the other defined fields in the Extended Buffer. Note that it is possible to have multiple host adapters loaded where the ASPI manager loaded for one card supports this Extended call, while the ASPI manager for the other card does not. In certain situations, this could cause the Extended Host Adapter Inquiry call to fail (e.g default back to standard Host Adapter Inquiry call). If the signature bytes are swapped (AA55h->55AAh), the Length of Extended Buffer field will also be modified to indicate now many bytes of the extended buffer were modified. This leaves us room to expand the meaning of the extended buffer in the future. For example, if an extended buffer size of 10 is passed in, though the ASPI manager loaded only supports the first 4 bytes, then the value of 4 will be returned in the Length of Extended Buffer field. Currently only the first eight bytes of the Extended Buffer are defined. The Extended buffer field is formatted as follows: OFFSET # BYTES DESCRIPTION R/W 3Ah (58) 02h (02) Features Word R Bits 15-4 Reserved Bit 3 0 = Not Wide SCSI 32 host adapter 1 = Wide SCSI 32 host adapter Bit 2 0 = Not Wide SCSI 16 host adapter 1 = Wide SCSI 16 host adapter Bit 1 0 = Residual byte length not reported 1 = Residual byte length reported Bit 0 0 = Scatter/Gather not supported 1 = Scatter/Gather supported 3Ch (60) 02h (02) Maximum Scatter/Gather list length R 3Eh (62) 04h (04) Maximum SCSI Data Transfer Length R The Feature Word bit fields defined above are self-explanatory. Note that if bit #2 is set, your ASPI module should scan SCSI IDs 0-15 on this host adapter for SCSI devices. The Scatter/Gather fields (including the scatter/gather list length) are currently only used by ASPI for OS/2. A Maximum SCSI Data Transfer Length of zero indicates no data transfer length limitation. A non-zero value indicates the largest value you should specify in the ASPI SRB Data Allocation Length (see ASPI Execute SRB function). IMPORTANT: Make sure you check the return value in the Length of Extended Buffer field to make certain that the field you are looking at is valid (e.g. if 4 is returned in the Length of Extended Buffer field, you should not use the value in the Maximum SCSI Data Transfer Length field). Now that I know my ASPI manager supports Residual Byte Length, how do I make use of it? The SCSI Request Flags byte is currently defined in the various ASPI specifications as follows: 7 6 5 4 3 2 1 0 Rsvd Rsvd S/G Direction Bits Rsvd Link Post NOTE: The S/G bit (scatter/gather) is currently only used under ASPI for OS/2. The new definition for this byte is as follows: 7 6 5 4 3 2 1 0 Rsvd Rsvd S/G Direction Bits Residual Link Post If bit #2 (Residual) is set to 1, and the ASPI manager supports residual byte length, then the residual byte length will be reported in the Data Allocation Length field within the SRB (bytes 0Ah-0Dh). On a typical command completion with all requested data transferred, and no residual bytes, the Data Allocation Length field will contain the value zero. NOTE: Adaptec EZ-SCSI v3.0 includes support for the residual byte feature.