HP OpenVMS Systems Documentation
OpenVMS I/O User's Reference Manual
A.4 Mailbox Driver
This section lists the function codes and function modifiers for themailbox driver.
1Only for write functions
2Only for read functions
A.5 Terminal Driver
This section lists the function codes and function modifiers for theterminal driver.
1Only for IO$_READPROMPT
2Only for itemlist read function. Do not specify with othermodifiers.
3Only for IO$_WRITELBLK and IO$_WRITEVBLK
4Only with IO$M_OUTBAND
5Only with IO$M_MAINT
6Itemlist: IO$V_LT_MAP_NODNAM, IO$V_LT_MAP_PORNAM,IO$V_LT_MAP_SRVNAM, IO$V_LT_MAP_LNKNAM, and IO$V_LT_MAP_NETADR.
A.6 Local Area Network Device Drivers
1Only for read functions
2Only for write functions
3See text for complete contents
4Use only with IO$M_CTRL alone or with IO$_STARTUP, that is,the set controller mode
A.7 Fast I/O Function Codes and Modifiers
A.8 Fast Path Function Codes and Modifiers
|P1||S2DGB base address|
|P3||Reserved, should be zero|
|P4||Reserved, should be zero|
|P5||Reserved, should be zero|
|P6||Reserved, should be zero|
The SCSI Diagnose Buffer (S2DGB) defined in STARLET now allows twoformats, one for 32-bit addressing and one for 64-bit addressing. The32-bit format is identical to the one supported on OpenVMS AlphaVersion 6.2.
Figure B-1 OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 32-BitLayout
Figure B-2 OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 64-BitLayout
A user application must specify which one of the two S2DGB formats isto 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) torequest 32-bit format, or OP_XCDB64 (= 2) to request 64-bit format.Once the value of OP_XCDB64 has been specified, the user application isobligated to use the 64-bit S2DGB format and, in particular, to use the64-bit names for S2DGB fields as described below. Likewise, an opcodevalue of OP_XCDB32 obligates the user application to use the 32-bitnames 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. Whenever afield has two different names for the 32-bit and 64-bit cases, the32-bit name is given first, and the 64-bit name is given after it inparentheses. Also, except for fields which contain addresses, allfields are unsigned longwords.
This field should contain either S2DGB$K_OP_XCDB32 orS2DGB$K_OP_XCDB64, depending on whether the user application intends tosupply 32-bit virtual addresses or 64-bit virtual addresses,respectively, in the other fields of the S2DGB.
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. Thisis required for compatibility with the IO$_DIAGNOSE interface availablein OpenVMS Alpha Version 6.1 and earlier.
|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 since 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 will cause 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$V_AUTOSENSE||When this bit is 1, S2DGB$L_32SENSEADDR and S2DGB$L_32SENSELEN should contain a valid sense buffer address and length. If a CHECK CONDITION or COMMAND TERMINATED status is returned, REQUEST SENSE data will be 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 zero.|
This field should contain the 32-bit (or 64-bit) virtual address of theSCSI command data block (CDB) to be sent to the target by thisIO$_DIAGNOSE operation.
Note that S2DGB$L_32CDBADDR is a pointer to a longword, whileS2DGB$PQ_64CDBADDR is a pointer to a quadword.
This field should contain the number of bytes in the SCSI command datablock (CDB) to be sent to the target by this IO$_DIAGNOSE operation.(Legal values: 2 to 248. However, some ports may restrict CDBs tosmaller lengths. Recommended values: 2 to 16.)
This field should contain the 32-bit (or 64-bit) virtual address of theDATAIN or DATAOUT buffer to be used with this SCSI operation. If theCDB being sent to the target does not use a DATAIN or DATAOUT buffer,then this field should be zero.
Note that S2DGB$L_32DATADDR is a pointer to a longword, whileS2DGB$PQ_64DATADDR is a pointer to a quadword.
This field should contain the number of bytes in the DATAIN or DATAOUTbuffer associated with this operation. If the CDB being sent to thetarget does not use a DATAIN or DATAOUT buffer, then this field shouldbe zero. (Legal values: 0 to UCB$L_MAXBCNT. Recommended values: 0 to65,536. All ports are required to support at least 65,536 byte datatransfers.)
This field should contain the number of padding DATAIN or DATAOUT bytesrequired by this operation. If S2DGB$V_TAGGED_REQ is 1, then the PADcount value will not be its default value. (Legal values: 0 to themaximum number of bytes in a disk block on this system minus one.Current legal values: 0 to 511.)
This field should contain the number of seconds that the port drivershould wait for a phase transition to occur or for delivery of anexpected interrupt. If S2DGB$V_ TAGGED_REQ is 1 or this field containsa 0 or 1, then the current phase transition timeout setting will not bechanged. (Legal values: 0 to 65,535 [about 18 hours].)
This field should contain the number of seconds that the port drivershould wait for a disconnected transaction to reconnect. IfS2DGB$V_TAGGED_REQ is 1 or this field contains a 0 or 1, then thecurrent disconnect timeout setting will not be changed. (Legal values:0 to 65,535 [about 18 hours].)
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 SCSIoperation. If S2DGB$V_AUTOSENSE is 0, this field will be ignored.
Note that S2DGB$L_32SENSEADDR is a pointer to a longword, whileS2DGB$PQ_64SENSEADDR is a pointer to a quadword.
If S2DGB$V_AUTOSENSE is 1, then this field should contain the number ofbytes in the sense buffer associated with this operation. (Legalvalues: 0 to 255. Note: a value of 0 instructs the class driver todiscard any sense data received. Recommended value: 18. Some ports mayrestrict the number of sense bytes to 18.) If S2DGB$V_AUTOSENSE is 0,this field will be ignored.
The following example shows how to set up a 64-bit S2DGB:
#include <s2dgbdef.h> /* Define S2DGB */#include <far_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)(&cdb);/* Command addr */ diag_desc.s2dgb$l_64cdblen = 6; /* Command length */ diag_desc.s2dgb$pq_64dataddr = (VOID_PQ)(&buf);/* 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)(&asn);/* 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, &iosb, 0, 0, &diag_desc, S2DGB$K_XCDB64_LENGTH, 0, 0, 0, 0);
If all arguments are valid, the class driver will invoke the necessaryport functions to send the CDB, transfer the data, and return, save ordiscard sense data as defined by the input S2DGB. Upon completion, thereturn IOSB will have the following format:
The DKDRIVER, GKDRIVER, and MKDRIVER class drivers, which implementother QIO functions, might intermix other tagged requests withIO$_DIAGNOSE requests. The order in which requests are sent generallymatches the order in which requests are presented to the driver. Anexception 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 immediately and nocommand will be sent to the target.
The DKDRIVER, GKDRIVER, and MKDRIVER class drivers permit only oneIO$_DIAGNOSE operation to be active (in the start I/O routine) at agiven time, except as described in the next paragraph. However,applications must single thread IO$_DIAGNOSE requests in order toproperly detect the presence of sense data and send the requiredREQUEST SENSE command. This is consistent with the VAX IO$_DIAGNOSEbehavior. For example, if three reads are issued with no waiting andthe first read gets a CHECK CONDITION, the sense data will be discardedby the target when the second read arrives.