Updated: 11 December 1998

OpenVMS I/O User's Reference Manual

Shadow set recovery and repair are handled by volume processing, which replaces mount verification for shadow sets. Membership failure decisions are made by the VAX hosts. Device errors that result in inaccessibility of physical member units first utilize the class driver's connection walking algorithm. If that fails, a local decision is made on the shadow set membership. The rules are:

• If some, but not all, members of the set are accessible, then the local node sequentially adjusts the membership and notifies the other hosts.
• If no members are accessible, no modifications to the set membership are made.

There are two types of volume processing: active and passive. Active volume processing handles error processing on a local node. Triggered by a failed I/O operation, active volume processing also controls mount verification functions, member removal, and failover. Passive volume processing is triggered by lock messages or by a cluster event. Passive volume processing revalidates shadow set membership, ensures that the shadow set reflects changes made outside the shadow set, and handles the following functions:

• Member additions from other nodes
• Member removals from other nodes
• A new node mounting the shadow set
• A node dismounting the shadow set
• A system crash on a node that has the shadow set mounted

For more information, see the Volume Shadowing for OpenVMS manual.

This chapter describes the use of the OpenVMS Generic Small Computer System Interface (SCSI) class driver.

8.1 Overview of SCSI

The American National Standard for information systems---Small Computer System Interface--2 (SCSI--2) specification defines mechanical, electrical, and functional requirements for connecting small computers to a wide variety of intelligent devices, such as rigid disks, flexible disks, magnetic tape devices, printers, optical disks, and scanners. It specifies standard electrical bus signals, timing, and protocol, as well as a standard packet interface for sending commands to devices on the SCSI bus.

Certain OpenVMS systems employ the SCSI bus as an I/O bus. For these systems, Compaq offers SCSI-compliant disk and tape drives, such as the RZ55 300 MB read/write disk, the RRD40 600 MB compact disk, and the TZK50 95 MB streaming tape drive. The operating system also allows devices including disk drives, tape drives, and scanners, supplied by sources other than Compaq, to be connected to the SCSI bus of such a system.

SCSI has been widely adopted by manufacturers for a variety of peripheral devices. However, because the ANSI SCSI standard is broad in scope, not all devices that implement its specifications can fully interrelate on the bus. Compaq fully supports SCSI-compliant equipment sold or supplied by Compaq. Proper operation of products not sold or supplied by Compaq cannot be assured.

For more information, refer to the following documents:

• American National Standard for Information Systems---Small Computer System Interface---2 (SCSI--2) specification (X3T9.2/86--109)
  Copies of this document may be purchased from: Global Engineering Documents, 2805 McGaw, Irvine, California 92714, United States; or (800) 854-7179 or (714) 261-1455. Please refer to document X3.131--198X.
• American National Standard for Information Systems---Small Computer System Interface specification (X3.131--1986)
  Copies of this document may be obtained from: American National Standards Institute, Inc., 1430 Broadway, New York, New York, 10018. This document is now known as the SCSI--1 standard.

Compaq publishes two additional documents to help third-party vendors prepare SCSI peripherals and peripheral software for use with DIGITAL workstations.

• The Small Computer System Interface: An Overview (EK--SCSISOV--001) provides a general description of the DIGITAL SCSI third-party support program.
• The Small Computer System Interface: A Developer's Guide (EK--SCSIS--SP--001) presents the details of implementation of SCSI within DIGITAL operating systems.

The operating system employs a class/port driver architecture to communicate with devices on the SCSI bus. The class/port design allows the responsibilities for communication between the operating system and the device to be cleanly divided between two separate driver modules (see Figure 8-1).

Figure 8-1 OpenVMS SCSI Class/Port Interface

The SCSI port driver transmits and receives SCSI commands and data. It knows the details of transmitting data from the local processor's SCSI port hardware across the SCSI bus. Although it understands SCSI bus phases, protocol, and timing, it has no knowledge of which SCSI commands the device supports, what status messages it returns, or the format of the packets in which this information is delivered. Strictly speaking, the port driver is a communications path. When directed by a SCSI class driver, the port driver forwards commands and data from the class driver onto the SCSI bus to the device. On any given OpenVMS system, a single SCSI port driver handles bus-level communications for all SCSI class drivers that may exist on the system.

The SCSI class driver acts as an interface between the user and the SCSI port, translating an I/O function as specified in a user's $QIO request to a SCSI command targeted to a device on the SCSI bus. Although the class driver knows about SCSI command descriptor buffers, status codes, and data, it has no knowledge of underlying bus protocols or hardware, command transmission, bus phases, timing, or messages. A single class driver can run on any given OpenVMS system, in conjunction with the SCSI port driver that supports that system. The operating system supplies a standard SCSI disk class driver and a standard SCSI tape class driver to support its disk and tape SCSI devices.

8.3 Overview of the OpenVMS Generic SCSI Class Driver

The OpenVMS generic SCSI class driver provides a mechanism by which an application program can control a SCSI device, supplied by a source other than Compaq, that cannot be controlled by the standard OpenVMS disk and tape class drivers. By means of a Queue I/O Request ($QIO) system service call, a program can pass to the generic SCSI class driver a preformatted SCSI command descriptor block. The generic SCSI class driver, in conjunction with the standard OpenVMS SCSI port driver, delivers this SCSI command to the device, manages any transfer of data from the device to a user buffer, and returns SCSI status to the application.

In effect, an application using the generic SCSI class driver implements details of device control usually managed within device driver code. The programmer of such an application must understand which SCSI commands the device supports and which SCSI status values the device returns. The programmer must also be aware of the device's timeout requirements, data transfer capabilities, and command retry behavior.

The application program sets up the characteristics of the connection the generic SCSI class driver uses when delivering commands to, exchanging data with, and receiving status from the device. The program associates each I/O operation the device can perform with a specific SCSI command. When it receives a request for a particular operation, the application program creates the specific command descriptor block that, when passed to the device, causes it to perform that operation.

The application initiates all transactions to the SCSI device by means of a $QIO call to the generic SCSI class driver, supplying the address and length of the SCSI command descriptor block, plus the parameters of any data transfer operation, in the call. When the transaction completes and the application program regains control, it interprets the returned status value, processes any returned data, and services any failure. To avoid conflicts with other applications accessing the same device, an application may need to explicitly allocate the device.

Because the generic SCSI class driver has no knowledge of specific device errors, it neither logs device errors nor implements error recovery. An application using the driver must manage device-specific errors itself. To service an error returned on a single transaction, the application must issue additional $QIO requests and initiate further transactions to the device. If more precise or more efficient error recovery is required for a device, the developer should consider writing a third-party SCSI class driver, as described in the OpenVMS VAX Device Support Manual. A third-party SCSI class driver can log errors associated with device activity by using the method described in the OpenVMS VAX Device Support Manual.

A third-party class driver is the only means of supporting devices that themselves generate transactions on the SCSI bus, such as notification of a device selection event to the host processor. See the description of asynchronous event notification (AEN) in the OpenVMS VAX Device Support Manual.

Figure 8-2 shows the flow of a $QIO request through the generic SCSI class driver and the port driver.

Figure 8-2 Generic SCSI Class Driver Flow

When direct access to a target device on the SCSI bus is required, the generic SCSI class driver is loaded for that device, as described in Section 8.6. An application program using the generic class driver performs the following tasks to issue a command to the target device:

1. Calls the Assign I/O Channel ($ASSIGN) system service to assign a channel to the generic SCSI class driver, and to allocate the device for the application's exclusive use.
2. Formats a SCSI command descriptor block.
3. Formats any data to be transferred to the device.
4. Calls the Queue I/O Request ($QIO) system service to request the generic SCSI class driver to send the SCSI command descriptor block to the port driver.
5. Upon completion of the I/O request, interprets the SCSI status byte and any data returned from the target device.

These operations are described in following sections.

Interactive commands and procedure calls can use the OpenVMS generic SCSI class driver to access devices on the SCSI bus. However, it is unlikely that a user application would access a device on the SCSI bus by directly using the $QIO interface of the generic SCSI class driver. First of all, any user process directly using the $QIO interface would require DIAGNOSE and PHY_IO or LOG_IO privileges. Under normal circumstances, it would be a system security risk to grant DIAGNOSE and PHY_IO or LOG_IO privileges to many system users. Secondly, it would be cumbersome for end users of the device to identify, format, and issue SCSI commands to the device. Rather, it would be more efficient to develop an interface that hides these details.

A utility program, installed with the DIAGNOSE and PHY_IO or LOG_IO privileges, can provide nonprivileged users with a command-line interface to a SCSI device. The utility translates interactive commands provided by the user into the appropriate set of SCSI commands and sends them to the device using the $QIO interface provided by the generic SCSI class driver. The utility checks user commands to ensure that only valid SCSI commands are sent to the device. See the OpenVMS System Manager's Manual and the OpenVMS System Management Utilities Reference Manual for information about installing images with privileges.

A privileged shareable image can provide system applications with a procedure interface to a SCSI device. The image contains a set of procedures that translate operations specified by the caller into the appropriate set of SCSI commands. The SCSI commands are sent to the device through the $QIO interface of the generic SCSI class driver. The privileged shareable image checks its caller's parameters to ensure that only valid SCSI commands are sent to the device. See the OpenVMS Programming Interfaces: Calling a System Routine for information about creating shareable images.

8.5 SCSI Port Features Under Application Control

The standard OpenVMS SCSI port driver provides mechanisms by which the generic SCSI class driver can control the nature of data transfers and command transmission across the SCSI bus. An application uses the $QIO interface to tailor these mechanisms to the specific device it supports. Among the features under application program control are the following:

• Data transfer mode
• Disconnection and reselection
• Command retry
• Command timeouts

The following sections discuss these features.

8.5.1 Setting the Data Transfer Mode

The SCSI bus defines two data transfer modes, asynchronous and synchronous. In asynchronous mode, for each REQ from a target there is an ACK from the host prior to the next REQ from the target. Synchronous mode allows higher data transfer rates by allowing a pipelined data transfer mechanism where, for short bursts (defined by the REQ-ACK offset), the target can pipeline data to an initiator without waiting for the initiator to respond.

Whether or not a port or a target device allows synchronous data transfers, it is harmless for the program to set up the connection to use such transfers. If synchronous mode is not supported, the port driver automatically uses asynchronous mode.

For example, to use synchronous mode in a transfer, a programmer using the generic SCSI class driver must ensure that both the SCSI port and the SCSI device involved in the transfer support synchronous mode. The SCSI port of the VAXstation 3520/3540 system allows both synchronous and asynchronous transfers, whereas that of OpenVMS 3100 systems supports only asynchronous transfers.

To set up a connection to use synchronous data transfer mode, a program using the generic SCSI class driver sets the syn bit in the flags field of the generic SCSI descriptor, the address of which is passed to the driver in the p1 argument to the $QIO request.

8.5.2 Enabling Disconnection and Reselection

The ANSI SCSI specification defines a disconnection facility that allows a target device to yield ownership of the SCSI bus while seeking or performing other time-consuming operations. When a target disconnects from the SCSI bus, it sends a sequence of messages to the initiator that cause it to save the state of the I/O transfer in progress. Once this is done, the target releases the SCSI bus. When the target is ready to complete the operation, it reselects the initiator and sends to it another sequence of messages. This sequence uniquely identifies the target and allows the initiator to restore the context of the suspended I/O operation.

Whether disconnection should be enabled or disabled on a given connection depends on the nature and capabilities of the device involved in the transfer, as well as on the configuration of the system. In configurations where there is a slow device present on the SCSI bus, enabling disconnection on connections that transfer data to the device can increase bus throughput. By contrast, systems where most of the I/O activity is directed towards a single device for long intervals can benefit from disabling disconnection. By disabling disconnection when there is no contention on the SCSI bus, port drivers can increase throughput and decrease the processor overhead for each I/O request.

By default, the OpenVMS class/port interface disables the disconnect facility on a connection. To enable disconnection, an application program using the generic SCSI class driver sets the dis bit of the flags field of the generic SCSI descriptor, the address of which is passed to the driver in the p1 argument to the $QIO call.

8.5.3 Disabling Command Retry

The SCSI port driver implements a command retry mechanism, which is enabled on a given connection by default.

When the command retry mechanism is enabled, the port driver retries up to three times any I/O operation that fails during the COMMAND, Message, Data, or STATUS phases. For instance, if the port driver detects a parity error during the Data phase, it aborts the I/O operation, logs an error, and retries the I/O operation. It repeats this sequence twice more, if necessary. If the I/O operation completes successfully during a retry attempt, the port driver returns success status to the class driver. However, if all retry attempts fail, the port driver returns failure status to the class driver.

An application may need to disable the command retry mechanism under certain circumstances. For example, repeated execution of a command on a sequential device may produce different results than are intended by a single command request. A tape drive could perform a partial write and then repeat the write without resetting the tape position.

An application program using the generic SCSI class driver can disable the command retry mechanism by setting the dpr bit of the flags field of the generic SCSI descriptor, the address of which is passed to the driver in the p1 argument to the $QIO request.

8.5.4 Setting Command Timeouts

The SCSI port driver implements several timeout mechanisms, some governed by the ANSI SCSI specification and others required by OpenVMS. The timeouts required by OpenVMS include the following:

Timeout	Description
Phase change timeout	Maximum number of seconds for a target to change the SCSI bus phase or complete a data transfer. (This value is also known as the DMA timeout.) Upon sending the last command byte, the port driver waits this many seconds for the target to change the bus phase lines and assert REQ (indicating a new phase). Or, if the target enters the DATA IN or DATA OUT phase, the transfer must be completed within this interval.
Disconnect timeout	Maximum number of seconds, from the time the initiator receives the DISCONNECT message, for a target to reselect the initiator so that it can proceed with the disconnected I/O transfer.

An application program using the generic SCSI class driver is responsible for maintaining both of these timeout values. It has the following options:

• Accepting a connection's default value. The default value for both timeouts is 20 seconds.
• Altering the connection's default value. To modify the default values, the class driver specifies nonzero values for the phase change timeout and disconnect timeout fields of the generic SCSI descriptor, the address of which is passed to the driver in the p1 argument to the $QIO system service call.

On VAX systems, the System Generation utility (SYSGEN) loads the generic SCSI class driver into system virtual memory, creates additional data structures for the device unit, and calls the driver's controller initialization routine and unit initialization routine. SYSGEN automatically loads and autoconfigures the SCSI port driver at system initialization. As part of autoconfiguration, SYSGEN polls each device on each SCSI bus. If the device identifies itself as a direct-access device, direct-access CD-ROM device, or flexible disk device, SYSGEN automatically loads the disk class driver (DKDRIVER). If the device identifies itself as a sequential-access device, SYSGEN automatically loads the tape class driver (MKDRIVER). If the autoconfiguration facility does not recognize the type of the SCSI device, it does not load a driver.

If a third-party-supplied SCSI device requires that the generic class driver be loaded, it must be configured by an explicit SYSGEN CONNECT command, as follows:

$ RUN SYS$SYSTEM:SYSGEN SYSGEN> CONNECT GKpd0u /NOADAPTER

On Alpha systems, SYSMAN performs the same functions that SYSGEN performs on VAX systems. If a third-party-supplied SCSI device requires that the generic class driver be loaded, the device must be configured by an explicit SYSMAN CONNECT command, as follows:

$ RUN SYS$SYSTEM:SYSMAN SYSMAN> IO CONNECT GKpd0u /NOADAPTER/DRIVER=SYS$GKDRIVER

On VAX and Alpha systems, GK is the device mnemonic for the generic SCSI class driver (GKDRIVER); p represents the SCSI port ID (for instance, the controller ID A or B); d represents the SCSI device ID (a digit from 0 to 7); 0 signifies the digit zero; and u represents the SCSI logical unit number (a digit from 0 to 7).

Multiple devices residing on any SCSI bus in the system can share GKDRIVER as a class driver, as long as a CONNECT command is issued for each target device that requires the driver.

Because just one connection can exist through the SCSI port driver to each target, the generic class driver cannot be used for a target if a different SCSI class driver is already connected to that target. For example, if the SCSI disk class driver has a connection to device ID 2 on the SCSI bus identified by SCSI port ID B (DKB200), the generic class driver cannot be used to communicate with this disk. An attempt to connect GKDRIVER for this target results in GKB200 being placed off line.

8.6.1 Disabling the Autoconfiguration of a SCSI Device (VAX Only)

On VAX systems, in special cases you may need to prevent the autoconfiguration facility from loading the disk or tape class driver for a device with a specific port ID and device ID. This would be the case if a SCSI device, supplied by a source other than Compaq, should identify itself as either a random-access or sequential-access device and were to be controlled by the generic SCSI class driver.

To disable the loading of a disk or tape driver for any given device ID, OpenVMS defines the special system parameter SCSI_NOAUTO.

The SCSI_NOAUTO system parameter, as shown in Figure 8-3, stores a bit mask of 32 bits in which the low-order byte corresponds to the first SCSI bus (PKA0), the second byte corresponds to the second SCSI bus (PKB0), and so on. For each SCSI bus, setting the low-order bit inhibits automatic configuration of the device with SCSI device ID 0; setting the second low-order bit inhibits automatic configuration of the device with SCSI device ID 1, and so forth. For instance, the value 00002000₁₆ would prevent the device with SCSI ID 5 on the bus identified by SCSI port ID B from being configured. By default, all of the bits in the mask are cleared, allowing all devices to be configured.

Figure 8-3 SCSI_NOAUTO System Parameter

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6136PRO_027.HTML