HP OpenVMS Systems Documentation

Shadow set recovery and repair are handled by volume processing, whichreplaces mount verification for shadow sets. Membership failuredecisions are made by the VAX hosts. Device errors that result ininaccessibility of physical member units first utilize the classdriver's connection walking algorithm. If that fails, a local decisionis 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, refer to the Volume Shadowing for OpenVMS manual.

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

8.1 Overview of SCSI

The American National Standard for information systems---Small ComputerSystem Interface--2 (SCSI--2) specification defines mechanical,electrical, and functional requirements for connecting small computersto a wide variety of intelligent devices, such as rigid disks, flexibledisks, magnetic tape devices, printers, optical disks, and scanners. Itspecifies standard electrical bus signals, timing, and protocol, aswell as a standard packet interface for sending commands to devices onthe SCSI bus.

Certain OpenVMS systems employ the SCSI bus as an I/O bus. For thesesystems, Compaq offers SCSI-compliant disk and tape drives, such as theRZ55 300 MB read/write disk, the RRD40 600 MB compact disk, and theTZK50 95 MB streaming tape drive. The operating system also allowsdevices including disk drives, tape drives, and scanners, supplied bysources other than Compaq, to be connected to the SCSI bus of such asystem.

SCSI has been widely adopted by manufacturers for a variety ofperipheral devices. However, because the ANSI SCSI standard is broad inscope, not all devices that implement its specifications can fullyinterrelate on the bus. Compaq fully supports SCSI-compliant equipmentsold or supplied by Compaq. Proper operation of products not sold orsupplied 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 vendorsprepare SCSI peripherals and peripheral software for use with DIGITALworkstations.

• 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 tocommunicate with devices on the SCSI bus. The class/port design allowsthe responsibilities for communication between the operating system andthe 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 SCSIcommands and data. It knows the details of transmitting data from thelocal processor's SCSI port hardware across the SCSI bus. Although itunderstands SCSI bus phases, protocol, and timing, it has no knowledgeof which SCSI commands the device supports, what status messages itreturns, or the format of the packets in which this information isdelivered. Strictly speaking, the port driver is a communications path.When directed by a SCSI class driver, the port driver forwards commandsand data from the class driver onto the SCSI bus to the device. On anygiven OpenVMS system, a single SCSI port driver handles bus-levelcommunications for all SCSI class drivers that may exist on the system.

The SCSI class driver acts as an interface between theuser and the SCSI port, translating an I/O function as specified in auser's $QIO request to a SCSI command targeted to a device on the SCSIbus. Although the class driver knows about SCSI command descriptorbuffers, status codes, and data, it has no knowledge of underlying busprotocols or hardware, command transmission, bus phases, timing, ormessages. A single class driver can run on any given OpenVMS system, inconjunction with the SCSI port driver that supports that system. Theoperating system supplies a standard SCSI disk class driver and astandard SCSI tape class driver to support its disk and tape SCSIdevices.

8.3 Overview of the OpenVMS Generic SCSI Class Driver

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

In effect, an application using the generic SCSI class driverimplements details of device control usually managed within devicedriver code. The programmer of such an application must understandwhich SCSI commands the device supports and which SCSI status valuesthe device returns. The programmer must also be aware of the device'stimeout requirements, data transfer capabilities, and command retrybehavior.

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

The application initiates all transactions to the SCSI device by meansof a $QIO call to the generic SCSI class driver, supplying the addressand length of the SCSI command descriptor block, plus the parameters ofany data transfer operation, in the call. When the transactioncompletes and the application program regains control, it interpretsthe returned status value, processes any returned data, and servicesany failure. To avoid conflicts with other applications accessing thesame device, an application may need to explicitly allocate the device.

Because the generic SCSI class driver has no knowledge of specificdevice errors, it neither logs device errors nor implements errorrecovery. An application using the driver must manage device-specificerrors itself. To service an error returned on a single transaction,the application must issue additional $QIO requests and initiatefurther transactions to the device. If more precise or more efficienterror recovery is required for a device, the developer should considerwriting a third-party SCSI class driver, as described in theOpenVMS VAX Device Support Manual (available on the Documentation CD-ROM). A third-partySCSI class driver can log errors associated with device activity byusing the method described in the OpenVMS VAX Device Support Manual (available on theDocumentation CD-ROM).

A third-party class driver is the only means of supporting devices thatthemselves generate transactions on the SCSI bus, such as notificationof a device selection event to the host processor. Refer to thedescription of asynchronous event notification (AEN) in theOpenVMS VAX Device Support Manual (available on the Documentation CD-ROM).

Figure 8-2 shows the flow of a $QIO request through the generic SCSIclass 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, thegeneric SCSI class driver is loaded for that device, as described inSection 8.6. An application program using the generic class driverperforms 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_IOprivileges, can provide nonprivileged users with a command-lineinterface to a SCSI device. The utility translates interactive commandsprovided by the user into the appropriate set of SCSI commands andsends them to the device using the $QIO interface provided by thegeneric SCSI class driver. The utility checks user commands to ensurethat only valid SCSI commands are sent to the device. Refer to theOpenVMS System Manager's Manual and the OpenVMS System Management Utilities Reference Manual for information about installingimages 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. Refer to the OpenVMS Programming Concepts Manual 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 andsynchronous. In asynchronous mode, for each REQ from a target there isan ACK from the host prior to the next REQ from the target. Synchronousmode allows higher data transfer rates by allowing a pipelined datatransfer mechanism where, for short bursts (defined by the REQ-ACKoffset), the target can pipeline data to an initiator without waitingfor the initiator to respond.

Whether or not a port or a target device allows synchronous datatransfers, it is harmless for the program to set up the connection touse such transfers. If synchronous mode is not supported, the portdriver 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 programusing the generic SCSI class driver sets the syn bitin the flags field of the generic SCSI descriptor, theaddress of which is passed to the driver in the p1argument to the $QIO request.

8.5.2 Enabling Disconnection and Reselection

The ANSI SCSI specification defines a disconnection facility thatallows a target device to yield ownership of the SCSI bus while seekingor performing other time-consuming operations. When a targetdisconnects from the SCSI bus, it sends a sequence of messages to theinitiator that cause it to save the state of the I/O transfer inprogress. Once this is done, the target releases the SCSI bus. When thetarget is ready to complete the operation, it reselects the initiatorand sends to it another sequence of messages. This sequence uniquelyidentifies the target and allows the initiator to restore the contextof the suspended I/O operation.

Whether disconnection should be enabled or disabled on a givenconnection depends on the nature and capabilities of the deviceinvolved in the transfer, as well as on the configuration of thesystem. In configurations where there is a slow device present on theSCSI bus, enabling disconnection on connections that transfer data tothe device can increase bus throughput. By contrast, systems where mostof the I/O activity is directed towards a single device for longintervals can benefit from disabling disconnection. By disablingdisconnection when there is no contention on the SCSI bus, port driverscan increase throughput and decrease the processor overhead for eachI/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 isenabled on a given connection by default.

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

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

An application program using the generic SCSI class driver can disablethe command retry mechanism by setting the dpr bit ofthe flags field of the generic SCSI descriptor, theaddress of which is passed to the driver in the p1argument to the $QIO request.

8.5.4 Setting Command Timeouts

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

An application program using the generic SCSI class driver isresponsible for maintaining both of these timeout values. It has thefollowing 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 thegeneric SCSI class driver into system virtual memory, createsadditional data structures for the device unit, and calls the driver'scontroller initialization routine and unit initialization routine.SYSGEN automatically loads and autoconfigures the SCSI port driver atsystem initialization. As part of autoconfiguration, SYSGEN polls eachdevice on each SCSI bus. If the device identifies itself as adirect-access device, direct-access CD-ROM device, or flexible diskdevice, SYSGEN automatically loads the disk class driver (DKDRIVER). Ifthe device identifies itself as a sequential-access device, SYSGENautomatically loads the tape class driver (MKDRIVER). If theautoconfiguration facility does not recognize the type of the SCSIdevice, it does not load a driver.

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

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

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

$ RUN SYS$SYSTEM:SYSMANSYSMAN> 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 shareGKDRIVER as a class driver, as long as a CONNECT command is issued foreach target device that requires the driver.

Because just one connection can exist through the SCSI port driver toeach target, the generic class driver cannot be used for a target if adifferent SCSI class driver is already connected to that target. Forexample, if the SCSI disk class driver has a connection to device ID 2on the SCSI bus identified by SCSI port ID B (DKB200), thegeneric class driver cannot be used to communicate with this disk. Anattempt to connect GKDRIVER for this target results in GKB200 beingplaced 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 theautoconfiguration facility from loading the disk or tape class driverfor a device with a specific port ID and device ID. This would be thecase if a SCSI device, supplied by a source other than Compaq, shouldidentify itself as either a random-access or sequential-access deviceand were to be controlled by the generic SCSI class driver.

To disable the loading of a disk or tape driver for any given deviceID, OpenVMS defines the special system parameterSCSI_NOAUTO.

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

Figure 8-3 SCSI_NOAUTO System Parameter