IO$_DIAGNOSE Function for SCSI Class Drivers

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP OpenVMS I/O User's Reference Manual

Fast Path Function Code and Modifiers

Tables

B	IO$_DIAGNOSE Function for SCSI Class Drivers

As of OpenVMS Version 7.0, the $QIO IO$_DIAGNOSE functionhas been enhanced to support 64-bit addressing for the followingSCSI class drivers: GKDRIVER, DKDRIVER, and MKDRIVER. This meansthat the virtual addresses specified within the S2DGB may now be64-bit virtual addresses if the user application requests it.

The $QIO IO$_DIAGNOSE arguments are still as follows:

Argument Use

P1
S2DGB base address

P2
S2DGB length

P3
Reserved, should be 0

P4
Reserved, should be 0

P5
Reserved, should be 0

P6
Reserved, should be 0

Argument	Use
P1	S2DGB base address
P2	S2DGB length
P3	Reserved, should be 0
P4	Reserved, should be 0
P5	Reserved, should be 0
P6	Reserved, should be 0

The SCSI Diagnose Buffer (S2DGB) defined in STARLET now allowstwo formats, one for 32-bit addressing and one for 64-bit addressing.The 32-bit format is identical to the one supported on OpenVMS AlphaVersion 6.2.

OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 32-Bit Layout shows the 32-bitS2DGB format. OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 64-Bit Layout showsthe 64-bit S2DGB format.

Figure 1 OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 32-BitLayout

Figure 2 OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 64-BitLayout

A user application must specify which one of the two S2DGBformats is to be used by passing a format value in S2DGB$L_OPCODE.Specifically, S2DGB$L_OPCODE must be assigned a value of eitherOP_XCDB32 (= 1) to request 32-bit format, or OP_XCDB64 (= 2) torequest 64-bit format. Once the value of OP_XCDB64 has been specified,the user application is obligated to use the 64-bit S2DGB formatand, in particular, to use the 64-bit names for S2DGB fields asdescribed below. Likewise, an opcode value of OP_XCDB32 obligatesthe user application to use the 32-bit names for the fields.

The correct length of the structure is defined by the constantS2DGB$K_XCDB32_LENGTH (value: 60-decimal), as well as by the constantS2DGB$K_XCDB64_LENGTH (value: 60-decimal).

The fields in the S2DGB are in the sections that follow. Whenevera field has two different names for the 32-bit and 64-bit cases,the 32-bit name is given first, and the 64-bit name is given afterit in parentheses. Also, except for fields that contain addresses,all fields are unsigned longwords.

S2DGB$L_OPCODE

This field should contain either S2DGB$K_OP_XCDB32 or S2DGB$K_OP_XCDB64,depending on whether the user application intends to supply 32-bitvirtual addresses or 64-bit virtual addresses, respectively, inthe other fields of the S2DGB.

S2DGB$L_FLAGS

This field should contain the bit fields shown in the followingtable. Note that these bit definitions start at bit 0 and omit nobits. This is required for compatibility with the IO$_DIAGNOSE interfaceavailable in OpenVMS Alpha Version 6.1 and earlier.

Table 1 S2DGB$L_FLAGS Bit Fields
Bit Field Description

S2DGB$V_READ
This bit should be 1 ifthe operation being performed is a read. If the operation is a write,this bit should be 0.

S2DGB$V_DISCPRIV
This bit should containthe DiscPriv bit value to be used in the IDENTIFY message sent withthis operation. If S2DGB$V_TAGGED_REQ is 1, then this bit is ignored.Note that S2DGB$V_DISCPRIV may be ignored by some ports unconditionally.

S2DGB$V_SYNCHRONOUS
This bit is ignored becauseits value is beyond the control of the user in SCSI-2 drivers.

S2DGB$V_OBSOLETE1
This bit is ignored. In previous releases,it represented the disabling of command retries, which is now beyondthe control of the user in SCSI-2 drivers.

S2DGB$V_TAGGED_REQ
When this bit is 1, theoperation is processed as using tagged command queuing and S2DGB$V_TAGshould define the tag value to be used. When this bit is 0, theoperation is processed without benefit of tagged command queuing.

Notethat although some ports do not support tagged command queuing,setting this bit to 1 will inhibit changing the values of S2DGB$L_32PADCNT(S2DGB$L_64PADCNT), S2DGB$L_32DSCTMO (S2DGB$L_64DSCTMO), and S2DGB$L_32PHSTMO(S2DGB$L_64PHSTMO), and will cause S2DGB$V_DISCPRIV to be ignored.Note also that some ports simulate untagged operations using appropriatelytagged operations. If S2DGB$V_TAGGED_REQ is 1, then this 3-bit field shouldcontain one of the following coded constant values:
S2DGB$K_SIMPLE indicates thatthe command is to be sent with the SIMPLE queue tag.
S2DGB$K_ORDERED indicates that the command is tobe sent with the ORDERED queue tab.
S2DGB$K_EXPRESS indicates that the command is tobe sent with the HEAD OF QUEUE queue tag.
If S2DGB$V_TAGGED_REQ is 0, then this field is ignored.Ports that do not support tagged command queuing always ignore the S2DGB$V_TAGfield and send all commands as untagged operations.

Note that automatic contingent allegiance processing is not accessiblethrough the IO$_DIAGNOSE function. Also, even though this is a 3-bitfield, only 2 bits are currently being utilized. That is, the 3constants above represent values, not bit positions.

S2DGB$V_AUTOSENSE
When this bit is 1, S2DGB$L_32SENSEADDRand S2DGB$L_32SENSELEN CONDITION or COMMAND TERMINATED status isreturned, REQUEST SENSE data will be returned in the buffer definedby S2DGB$L_32SENSEADDR and S2DGB$L_32SENSELEN.

WhenS2DGB$V_AUTOSENSE is 0, the buffer described by S2DGB$L_32SENSEADDRand S2DGB$L_32SENSELEN is ignored. In such cases, the class driversaves the autosense data in pool and returns it to the next IO$_DIAGNOSE,if and only if that IO$_DIAGNOSE has a REQUEST SENSE CDB.

Allother bits in S2DGB$L_FLAGS should be 0.

S2DGB$L_32CDBADDR (S2DGB$PQ_64CDBADDR)

This field should contain the 32-bit (or 64-bit) virtual addressof the SCSI command data block (CDB) to be sent to the target bythis IO$_DIAGNOSE operation.

Note that S2DGB$L_32CDBADDR is a pointer to a longword, whileS2DGB$PQ_64CDBADDR is a pointer to a quadword.

S2DGB$L_32CDBLEN (S2DGB$L_64CDBLEN)

This field should contain the number of bytes in the SCSIcommand data block (CDB) to be sent to the target by this IO$_DIAGNOSEoperation. (Legal values: 2 to 248; however, some ports may restrictCDBs to smaller lengths. Recommended values: 2 to 16.)

S2DGB$L_32DATADDR (S2DGB$PQ_64DATADDR)

This field should contain the 32-bit (or 64-bit) virtual addressof the DATAIN or DATAOUT buffer to be used with this SCSI operation.If the CDB being sent to the target does not use a DATAIN or DATAOUTbuffer, then this field should be 0.

Note that S2DGB$L_32DATADDR is a pointer to a longword, whileS2DGB$PQ_64DATADDR is a pointer to a quadword.

S2DGB$L_32DATLEN (S2DGB$L_64DATLEN)

This field should contain the number of bytes in the DATAINor DATAOUT buffer associated with this operation. If the CDB beingsent to the target does not use a DATAIN or DATAOUT buffer, thenthis field should be 0. (Legal values: 0 to UCB$L_MAXBCNT. Recommendedvalues: 0 to 65,536. All ports are required to support at least65,536 byte data transfers.)

S2DGB$L_32PADCNT (S2DGB$L_64PADCNT)

This field should contain the number of padding DATAIN orDATAOUT bytes required by this operation. If S2DGB$V_TAGGED_REQis 1, then the PAD count value will not be its default value. (Legalvalues: 0 to the maximum number of bytes in a disk block on thissystem minus one. Current legal values: 0 to 511.)

S2DGB$L_32PHSTMO (S2DGB$L_64PHSTMO)

This field should contain the number of seconds that the portdriver should wait for a phase transition to occur or for deliveryof an expected interrupt. If S2DGB$V_ TAGGED_REQ is 1 or this fieldcontains a 0 or 1, then the current phase transition timeout settingwill not be changed. (Legal values: 0 to 65,535 [about 18 hours].)

S2DGB$L_32DSCTMO (S2DGB$L_64DSCTMO)

This field should contain the number of seconds that the portdriver should wait for a disconnected transaction to reconnect.If S2DGB$V_TAGGED_REQ is 1 or this field contains a 0 or 1, thenthe current disconnect timeout setting will not be changed. (Legalvalues: 0 to 65,535 [about 18 hours].)

S2DGB$L_32SENSEADDR (S2DGB$PQ_64SENSEADDR)

If S2DGB$V_AUTOSENSE is 1, then this field should containthe 32-bit (or 64-bit) virtual address of the sense buffer to beused by this SCSI operation. If S2DGB$V_AUTOSENSE is 0, this fieldwill be ignored.

Note that S2DGB$L_32SENSEADDR is a pointer to a longword,while S2DGB$PQ_64SENSEADDR is a pointer to a quadword.

S2DGB$L_32SENSELEN (S2DGB$L_64SENSELEN)

If S2DGB$V_AUTOSENSE is 1, then this field should containthe number of bytes in the sense buffer associated with this operation.(Legal values: 0 to 255. Note that a value of 0 instructs the classdriver to discard any sense data received. Recommended value: 18.Some ports may restrict the number of sense bytes to 18.) If S2DGB$V_AUTOSENSEis 0, this field will be ignored.

The following example shows how to set up a 64-bit S2DGB:

#include                                   /* Define S2DGB   */#include _pointers.h>                              /* Define VOID_PQ */    S2DGB diag_desc;    /* Set up some default S2DGB descriptor values */    diag_desc.s2dgb$l_opcode = OP_XCDB64               /* Use 64-bits  */   diag_desc.s2dgb$l_flags =  (S2DGB$M_READ |         /* Flags*/                         S2DGB$M_TAGGED_REQ |                          S2DGB$M_AUTOSENSE);   diag_desc.s2dgb$v_tag = S2DGB$K_SIMPLE;           /* SIMPLE que tag */   diag_desc.s2dgb$pq_64cdbaddr = (VOID_PQ)([0]);/* Command addr  */   diag_desc.s2dgb$l_64cdblen =  6;                  /* Command length */   diag_desc.s2dgb$pq_64dataddr = (VOID_PQ)([0]);/* Data addr      */   diag_desc.s2dgb$l_64datlen = 20;                  /* Data length    */   diag_desc.s2dgb$l_64padcnt = 0;                   /* Pad length    */   diag_desc.s2dgb$l_64phstmo = 20;                  /* Phase timeout */   diag_desc.s2dgb$l_64dsctmo = 10;                  /* Disc timeout  */   diag_desc.s2dgb$pq_64senseaddr = (VOID_PQ)([0]);/* Autosense addr */    diag_desc.s2dgb$l_64senselen = 255;               /* Sense length  */   diag_desc.s2dgb$l_reserved_1 = 0;                 /* Reserved     */        .        .        . 		   status = sys$qiow(0, target_chan, IO$_DIAGNOSE, , 0, 0,             _desc,  S2DGB$K_XCDB64_LENGTH,  0,  0,  0,  0);

If all arguments are valid, the class driver will invoke thenecessary port functions to send the CDB, transfer the data, andreturn, save or discard sense data as defined by the input S2DGB.Upon completion, the return IOSB will have the following format: Return IOSB Format

The DKDRIVER, GKDRIVER, and MKDRIVER class drivers, whichimplement other QIO functions, might intermix other tagged requestswith IO$_DIAGNOSE requests. The order in which requests are sent generallymatches the order in which requests are presented to the driver.An exception to this ordering occurs when the driver receives REQUESTSENSE for which autosense data previously has been recovered andstored. In this case, the IO$_DIAGNOSE will complete immediatelyand no command will be sent to the target.

The DKDRIVER, GKDRIVER, and MKDRIVER class drivers permitonly one IO$_DIAGNOSE operation to be active (in the start I/O routine)at a given time, except as described in the next paragraph. However, applicationsmust single thread IO$_DIAGNOSE requests to properly detect thepresence of sense data and send the required REQUEST SENSE command.This is consistent with the VAX IO$_DIAGNOSE behavior. For example,if three reads are issued with no waiting and the first read getsa CHECK CONDITION, the sense data will be discarded by the targetwhen the second read arrives.

The DKDRIVER, GKDRIVER, and MKDRIVER drivers permit more thanone IO$_DIAGNOSE operation to be active (in the start I/O routine)only when all active operations have the S2DGB$V_AUTOSENSE flag equalto 1. Upon encountering the first IO$_DIAGNOSE with S2DGB$V_AUTOSENSEequal to 0, the class driver will apply the restrictions describedin the previous paragraph.

Fast Path Function Code and Modifiers

Tables