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.

Functions	Arguments	Modifiers
IO$_READVBLK IO$_READLBLK IO$_READPBLK IO$_WRITEVBLK IO$_WRITELBLK IO$_WRITEPBLK	P1---buffer address P2---buffer size	IO$M_NOW IO$M_NORSWAIT ¹ IO$M_READERCHECK ¹ IO$M_WRITERCHECK ² IO$M_STREAM ²
IO$_WRITEOF	None	IO$M_NOW IO$M_READERCHECK IO$M_STREAM
IO$_SETMODE!IO$M_READATTN IO$_SETMODE!IO$M_WRTATTN IO$_SETMODE!IO$MB_ROOM_NOTIFY	P1---AST address P2---AST parameter P3---access mode	None
+IO$_SETMODE!IO$M_READERWAIT +IO$_SETMODE!IO$M_WRITERWAIT	None	None
IO$_SETMODE!IO$M_SETPROT	P2---volume protection mask	None
+IO$_SENSEMODE!IO$M_READERCHECK +IO$_SENSEMODE!IO$M_WRITERCHECK	None	None

¹Only for write functions
²Only for read functions
+VAX specific

QIO Status Returns in R0
SS$_ACCVIO	SS$_EXQUOTA	SS$_ILLIOFUNC	SS$INSFMEM
SS$MBFULL	SS$_MBTOOSML	SS$_NOPRIV	SS$_NORMAL

IOSB Status Returns
SS$_ABORT	SS$_BUFFEROVF	SS$_CANCEL	SS$_ENDOFFILE
SS$_NOREADER	SS$_NORMAL	SS$_NOWRITER

A.5 Terminal Driver

This section lists the function codes and function modifiers for theterminal driver.

Functions	Arguments	Modifiers
IO$_READVBLK IO$_READLBLK IO$_READPROMPT	P1---buffer address P2---buffer size P3---timeout P4---read terminator block address P5---prompt string buffer address P6---prompt string buffer size ¹	IO$M_NOECHO IO$M_CVTLOW IO$M_NOFILTR IO$M_TIMED IO$M_PURGE IO$M_DSABLMBX IO$M_TRMNOECHO IO$M_ESCAPE
IO$_READVBLK	P1---buffer address P2---buffer size P3---access mode to probe itemlist P4---(zero) P5---itemlist buffer address P6---itemlist buffer size	IO$M_EXTEND ²
IO$_WRITEVBLK IO$_WRITELBLK IO$_WRITEPBLK	P1---buffer address P2---buffer size P3---(ignored) P4---carriage control specifier ³	IO$M_CANCTRLO IO$M_ENABLMBX IO$M_NOFORMAT IO$M_REFRESH IO$M_BREAKTHRU
IO$_SETMODE IO$_SETCHAR	P1---characteristics buffer address P2---characteristics buffer size P3---speed specifier P4---fill specifier P5---parity flags
IO$_SETMODE IO$_SETCHAR	None	IO$M_HANGUP
IO$_SETMODE	P1---buffer address P2---buffer size	IO$M_BRDCST
IO$_SETMODE IO$_SETCHAR	P1---AST service routine address P2---AST parameter P3---access mode to deliver AST	IO$M_CTRLCAST IO$M_CTRLYAST
IO$_SETMODE IO$_SETCHAR	P1---AST service routine address P2---character mask address P3---access mode to deliver AST	IO$M_OUTBAND IO$M_TT_ABORT ⁴ IO$M_INCLUDE ⁴
IO$_SETMODE IO$_SETCHAR	P1---address of control signals	IO$M_SET_MODEM ⁵ IO$M_MAINT
IO$_SETMODE IO$_SETCHAR	None	IO$M_LOOP ⁵ IO$M_UNLOOP ⁵ IO$M_MAINT
IO$_TTY_PORT		IO$M_LT_CONNECT IO$M_LT_DISCON
IO$_TTY_PORT	P1---itemlist ⁶ address P2---queued status	IO$M_LT_MAP_PORT
IO$_TTY_PORT	P1---service name descriptor address P2---service rating	IO$M_LT_RATING
IO$_TTY_PORT	P1---itemlist address P2---itemlist length P3---entity type P4---entity string descriptor	IO$M_LT_SENSEMODE
IO$_TTY_PORT	P1---itemlist address P2---itemlist length P3---entity type P4---entity string descriptor	IO$M_LT_SETMODE
IO$_SENSEMODE IO$_SENSECHAR	P1---characteristics buffer address P2---characteristics buffer size	IO$M_TYPEAHDCNT
IO$_SENSEMODE IO$_SENSECHAR	P1---address of input modem signal block	IO$M_RD_MODEM
IO$_SENSEMODE	P1---buffer address P2---buffer size	IO$M_BRDCST

¹Only for IO$_READPROMPT
²Only for itemlist read function. Do not specify with othermodifiers.
³Only for IO$_WRITELBLK and IO$_WRITEVBLK
⁴Only with IO$M_OUTBAND
⁵Only with IO$M_MAINT
⁶Itemlist: 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.

QIO Status Returns
SS$_ABORT	SS$_BADESCAPE	SS$_BADPARAM
SS$_CANCEL	SS$_CHANINTLK	SS$_CONTROLC
SS$_CONTROLO	SS$_CONTROLY	SS$_DATAOVERUN
SS$_INCOMPAT	SS$_NORMAL	SS$_PARITY
SS$_PARTESCAPE	SS$_TIMEOUT

A.6 Local Area Network Device Drivers

This section lists the function codes and function modifiers for thelocal area network drivers.

Functions	Arguments	Modifiers
IO$_READLBLK IO$_READVBLK IO$_READPBLK IO$_WRITELBLK IO$_WRITEVBLK IO$_WRITEPBLK	P1---buffer address P2---buffer size P4---802 format fields (optional) ³ P5---destination address (optional) ³	IO$M_NOW ¹ IO$M_RESPONSE ²
IO$_SETMODE IO$_SETCHAR	P2---extended characteristics buffer (optional) ⁴	IO$M_CTRL IO$M_STARTUP IO$M_SHUTDOWN
IO$_SETMODE IO$_SETCHAR	P1---AST service address P3 -- access mode to deliver AST	IO$M_ATTNAST
IO$_SENSEMODE IO$_SENSECHAR	P1---device characteristics buffer (optional) P2---extended characteristics buffer (optional)	IO$M_CTRL

¹Only for read functions
²Only for write functions
³See text for complete contents
⁴Use only with IO$M_CTRL alone or with IO$_STARTUP, that is,the set controller mode

QIO Status Returns
SS$_ABORT	SS$_ACCVIO	SS$_BADPARAM
SS$_BUFFEROVF	SS$_COMMHARD	SS$_CTRLERR
SS$_DATACHECK	SS$_DATAOVERUN	SS$_DEVACTIVE
SS$_DEVALLOC	SS$_DEVINACT	SS$_DEVOFFLINE
SS$_DEVREQERR	SS$_DISCONNECT	SS$_DUPUNIT
SS$_ENDOFFILE	SS$_EXQUOTA	SS$_INSFMEM
SS$_INSFMAPREG	SS$_IVBUFLEN	SS$_MEDOFL
SS$_NOPRIV	SS$_NORMAL	SS$_OPINCOMPL
SS$_TIMEOUT	SS$_TOOMUCHDATA

A.7 Fast I/O Function Codes and Modifiers

This section lists the function codes and parameters for the $IO_SETUPsystem service.

Functions	Arguments
IO$_READVBLK IO$_READLBLK IO$_WRITEVBLK IO$_WRITELBLK	bufobj - user's buffer iosobj---I/O Status Area (IOSA) astadr---Completion AST routine flags---longword mask return_fandle---fandle address

A.8 Fast Path Function Codes and Modifiers

This section lists the function codes and function modifiers for FastPath.

Functions	Arguments	Modifiers
IO$_SETPRFPATH	P1---CPU mask None	IO$M_PREFERRED_CPU IO$M_SYS_ASSIGNABLE

Appendix B
IO$_DIAGNOSE Function for SCSI Class Drivers

As of OpenVMS Version 7.0, the $QIO IO$_DIAGNOSE function has beenenhanced to support 64-bit addressing for the following SCSI classdrivers: GKDRIVER, DKDRIVER, and MKDRIVER. This means that the virtualaddresses specified within the S2DGB may now be 64-bit virtualaddresses 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 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 shows the 32-bit S2DGB format. Figure B-2 shows the64-bit S2DGB format.

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.

S2DGB$L_OPCODE

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.

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. Thisis required for compatibility with the IO$_DIAGNOSE interface availablein 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 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$K_ORDERED indicates that the command is to be sent with the ORDERED queue tag. 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 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.

S2DGB$L_32CDBADDR (S2DGB$PQ_64CDBADDR)

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.

S2DGB$L_32CDBLEN (S2DGB$L_64CDBLEN)

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.)

S2DGB$L_32DATADDR (S2DGB$PQ_64DATADDR)

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.

S2DGB$L_32DATLEN (S2DGB$L_64DATLEN)

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.)

S2DGB$L_32PADCNT (S2DGB$L_64PADCNT)

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.)

S2DGB$L_32PHSTMO (S2DGB$L_64PHSTMO)

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].)

S2DGB$L_32DSCTMO (S2DGB$L_64DSCTMO)

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].)

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 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.

S2DGB$L_32SENSELEN (S2DGB$L_64SENSELEN)

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[0]);/* Command addr  */   diag_desc.s2dgb$l_64cdblen =  6;                  /* Command length */   diag_desc.s2dgb$pq_64dataddr = (VOID_PQ)(&buf[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)(&asn[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, &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.

Contents

Index