As of OpenVMS Version 7.0, the $QIO IO$_DIAGNOSE
function has been enhanced to support 64-bit addressing for the following
SCSI class drivers: GKDRIVER, DKDRIVER, and MKDRIVER. This means that
the virtual addresses specified within the S2DGB may now be 64-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 |
The SCSI Diagnose Buffer (S2DGB) defined in STARLET
now allows two formats, one for 32-bit addressing and one for 64-bit
addressing. The 32-bit format is identical to the one supported on
OpenVMS Alpha Version 6.2.
Figure B-1 shows the 32-bit S2DGB format. Figure B-2 shows the 64-bit S2DGB format.
A user application must specify which one of the
two S2DGB formats is to be used by passing a format value in S2DGB$L_OPCODE.
Specifically, S2DGB$L_OPCODE must be assigned a value of either OP_XCDB32
(= 1) to request 32-bit format, or OP_XCDB64 (= 2) to request 64-bit
format. Once the value of OP_XCDB64 has been specified, the user application
is obligated to use the 64-bit S2DGB format and, in particular, to
use the 64-bit names for S2DGB fields as described below. Likewise,
an opcode value of OP_XCDB32 obligates the user application to use
the 32-bit names for the fields.
The correct length of the structure is defined
by the constant S2DGB$K_XCDB32_LENGTH (value: 60-decimal), as well
as by the constant S2DGB$K_XCDB64_LENGTH (value: 60-decimal).
The fields in the S2DGB are in the sections that
follow. Whenever a 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 after it 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-bit virtual addresses or 64-bit virtual addresses, respectively,
in the other fields of the S2DGB.
S2DGB$L_FLAGS
This field should contain the bit fields shown
in the following table. Note that these bit definitions start at bit
0 and omit no bits. This is required for compatibility with the IO$_DIAGNOSE
interface available in OpenVMS Alpha Version 6.1 and earlier.
Table B-1 S2DGB$L_FLAGS Bit Fields
Bit Field | Description |
|---|
S2DGB$V_READ | This bit should be 1
if the operation being performed is a read. If the operation is a
write, this bit should be 0. |
S2DGB$V_DISCPRIV | This bit should contain
the DiscPriv bit value to be used in the IDENTIFY message sent with
this 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 because
its 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 beyond the control of the user in SCSI-2 drivers. |
S2DGB$V_TAGGED_REQ | When this bit is 1, the
operation is processed as using tagged command queuing and S2DGB$V_TAG
should define the tag value to be used. When this bit is 0, the operation
is processed without benefit of tagged command queuing. Note that 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 causes S2DGB$V_DISCPRIV to be ignored. Note
also that some ports simulate untagged operations using appropriately
tagged operations. If S2DGB$V_TAGGED_REQ is 1, then this 3-bit field
should contain one of the following coded constant values: S2DGB$K_SIMPLE indicates that the command is to be
sent with the SIMPLE queue tag. S2DGB$K_ORDERED indicates that the command is to be
sent with the ORDERED queue tab. S2DGB$K_EXPRESS indicates that the command is to be
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_TAG field and send all commands as untagged operations. Note that automatic contingent allegiance processing is not
accessible through the IO$_DIAGNOSE function. Also, even though this
is a 3-bit field, only 2 bits are currently being utilized. That is,
the 3 constants above represent values, not bit positions.
|
S2DGB$V_AUTOSENSE | When this bit is 1, S2DGB$L_32SENSEADDR
and S2DGB$L_32SENSELEN CONDITION or COMMAND TERMINATED status is returned,
REQUEST SENSE data is returned in the buffer defined by S2DGB$L_32SENSEADDR
and S2DGB$L_32SENSELEN. When S2DGB$V_AUTOSENSE is 0, the
buffer described by S2DGB$L_32SENSEADDR and S2DGB$L_32SENSELEN is
ignored. In such cases, the class driver saves 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. All other 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 address of the SCSI command data block (CDB) to be sent to
the target by this IO$_DIAGNOSE operation.
Note that S2DGB$L_32CDBADDR is a pointer to a
longword, while S2DGB$PQ_64CDBADDR is a pointer to a quadword.
S2DGB$L_32CDBLEN (S2DGB$L_64CDBLEN)
This field should contain the number of bytes
in the SCSI command data block (CDB) to be sent to the target by this
IO$_DIAGNOSE operation. (Legal values: 2 to 248; however, some ports
may restrict CDBs 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 address of 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 DATAOUT buffer, then this field should be 0.
Note that S2DGB$L_32DATADDR is a pointer to a
longword, while S2DGB$PQ_64DATADDR is a pointer to a quadword.
S2DGB$L_32DATLEN (S2DGB$L_64DATLEN)
This field should contain the number of bytes
in the DATAIN or DATAOUT buffer associated with this operation. If
the CDB being sent to the target does not use a DATAIN or DATAOUT
buffer, then this field should be 0. (Legal values: 0 to UCB$L_MAXBCNT.
Recommended values: 0 to 65,536. All ports are required to support
at least 65,536 byte data transfers.)
S2DGB$L_32PADCNT (S2DGB$L_64PADCNT)
This field should contain the number of padding
DATAIN or DATAOUT bytes required by this operation. If S2DGB$V_TAGGED_REQ
is 1, then the PAD count value is not its default value. (Legal values:
0 to the maximum number of bytes in a disk block on this system minus
one. Current legal values: 0 to 511.)
S2DGB$L_32PHSTMO (S2DGB$L_64PHSTMO)
This field should contain the number of seconds
that the port driver should wait for a phase transition to occur or
for delivery of an expected interrupt. If S2DGB$V_ TAGGED_REQ is 1
or this field contains a 0 or 1, then the current phase transition
timeout setting will 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 port driver should wait for a disconnected transaction to
reconnect. If S2DGB$V_TAGGED_REQ is 1 or this field contains a 0 or
1, then the current disconnect timeout setting will not be changed.
(Legal values: 0 to 65,535 (about 18 hours).)
S2DGB$L_32SENSEADDR (S2DGB$PQ_64SENSEADDR)
If S2DGB$V_AUTOSENSE is 1, then this field should
contain the 32-bit (or 64-bit) virtual address of the sense buffer
to be used by this SCSI operation. If S2DGB$V_AUTOSENSE is 0, this
field is 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
contain the number of bytes in the sense buffer associated with this
operation. (Legal values: 0 to 255. Note that a value of 0 instructs
the class driver to discard any sense data received. Recommended value:
18. Some ports may restrict the number of sense bytes to 18.) If S2DGB$V_AUTOSENSE
is 0, this field is 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 invokes
the necessary port functions to send the CDB, transfer the data, and
return, save or discard sense data as defined by the input S2DGB.
Up on completion, the return IOSB has the following format: 
The DKDRIVER, GKDRIVER, and MKDRIVER class drivers,
which implement other QIO functions, might intermix other tagged requests
with IO$_DIAGNOSE requests. The order in which requests are sent generally
matches the order in which requests are presented to the driver. An
exception to this ordering occurs when the driver receives REQUEST
SENSE for which autosense data previously has been recovered and stored.
In this case, the IO$_DIAGNOSE completes immediately and no command
is sent to the target.
The DKDRIVER, GKDRIVER, and MKDRIVER class drivers
permit only 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, applications must single thread IO$_DIAGNOSE requests to
properly detect the presence 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 gets a CHECK CONDITION, the sense data is discarded by the target
when the second read arrives.
The DKDRIVER, GKDRIVER, and MKDRIVER drivers permit
more than one IO$_DIAGNOSE operation to be active (in the start I/O
routine) only when all active operations have the S2DGB$V_AUTOSENSE
flag equal to 1. Upon encountering the first IO$_DIAGNOSE with S2DGB$V_AUTOSENSE
equal to 0, the class driver applies the restrictions described in
the previous paragraph.
