8.8 Issuing a $QIO Request to the Generic Class Driver

The format of the Queue I/O Request ($QIO) system service that initiates a request to the SCSI generic class driver is as follows. This explanation concentrates on the special elements of a $QIO request to the SCSI generic class driver. For a detailed description of the $QIO system service, see the HP OpenVMS System Services Reference Manual.

VAX MACRO Format

$QIO [efn] ,chan ,func ,iosb ,[astadr] ,[astprm] ,p1 ,p2 [,p3] [,p4] [,p5] [,p6]

High-Level Language Format

SYS$QIO ([efn] ,chan ,func ,iosb ,[astadr] ,[astprm] ,p1 ,p2 [,p3] [,p4] [,p5] [,p6])

Arguments

chan

I/O channel assigned to the device to which the request is directed. The chan argument is a word value containing the number of the channel, as returned by the Assign I/O Channel ($ASSIGN) system service.

func

Longword value containing the IO$_DIAGNOSE function code. Only the IO$_DIAGNOSE function code is implemented in the generic SCSI class driver.

iosb

See . The iosb argument is required in a request to the generic SCSI class driver; it has the following format:

The status code provides the final status indicating the success or failure of the SCSI command. The SCSI status byte contains the status value returned from the target device, as defined in the ANSI SCSI specification. The transfer count field specifies the actual number of bytes transferred during the SCSI bus DATA IN or DATA OUT phase

[efn], [astadr], [astprm]

These arguments apply to $QIO system service completion. For an explanation of these arguments, see the HP OpenVMS System Services Reference Manual.

p1

Address of a generic SCSI descriptor of the following format:

p2

Length of the generic SCSI descriptor.

Descriptor Fields

opcode

Currently, the only supported opcode is 1, indicating a pass-through function. Other opcode values are reserved for future expansion.

flags

Bit map having the following format:

Bits in the flags bit map are defined as follows:

Field	Definition
dir	Direction of transfer. If this bit is set, the target is expected at some time to enter the DATA IN phase to send data to the host. To facilitate this, the port driver maps the specified data buffer for write access. If this bit is clear, the target is expected at some time to enter the DATA OUT phase to receive data from the host. To facilitate this, the port driver maps the specified data buffer for read access. The generic SCSI class driver ignores the dir flag if either the SCSI data address or SCSI data length field of the generic SCSI descriptor is zero.
dis	Enable disconnection. If this bit is set, the target device is allowed to disconnect during the execution of the command. If this bit is clear, the target cannot disconnect during the execution of the command. Note that targets that hold on to the bus for long periods of time without disconnecting can adversely affect system performance. See “Enabling Disconnection and Reselection” for additional information.
syn	Enable synchronous mode. If this bit is set, the port driver uses synchronous mode for data transfers, if both the host and target allow this mode of operation. If this bit is clear, or synchronous mode is not supported by either the host or target, the port driver uses asynchronous mode for data transfers. See “Setting the Data Transfer Mode” for additional information.
dpr	Disable port retry. If this bit is clear, the port driver retries, up to three times, any command that fails with a timeout, bus parity, or invalid phase transition error. If this bit is set, the port driver does not retry commands for which it detects failure. See “Disabling Command Retry” for additional information.

SCSI command address

Address of a buffer containing a SCSI command.

SCSI command length

Length of the SCSI command. The maximum length of the SCSI command is 128 bytes.

SCSI data address

Address of a data buffer associated with the SCSI command.

If the dir bit is set in the flags field, data is written into this buffer during the execution of the command. Otherwise, data is read from this buffer and sent to the target device.

If the SCSI command requires no data to be transferred, then the SCSI data address field should be clear.

SCSI data length

Length, in bytes, of the data buffer pointed to by the SCSI data address field. The maximum data buffer size is 65,535 bytes.

If the SCSI command requires no data to be transferred, then this field should be clear.

SCSI pad length

This field is used to accommodate SCSI device classes that require that the transfer length be specified in terms of a larger data unit than the count of bytes expressed in the SCSI data length field. If the total amount of data requested in the SCSI command does not match that specified in the SCSI data length field, this field must account for the difference.

For example, suppose an application program is using the generic class driver to read the first 2 bytes of a disk block. The length field in the SCSI READ command contains 1 (indicating one logical block, or 512 bytes), while the SCSI data length field contains a 2. The SCSI pad length field must contain the difference, 510 bytes.

For most transfers, this field should contain 0. Failure to initialize the SCSI pad length field properly causes port driver timeouts and SCSI bus resets.

phase change timeout

Maximum number of seconds for a target to change the SCSI bus phase or complete a data transfer. A value of 0 causes the SCSI port driver's default phase change timeout value of 4 seconds to be used.

See “Setting Command Timeouts” for additional information.

disconnect timeout

Maximum number of seconds for a target to reselect the initiator to proceed with a disconnected I/O transfer. A value of 0 causes the SCSI port driver's default disconnect timeout value of 4 seconds to be used.

See “Setting Command Timeouts” for additional information.